diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..f6df6137 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,147 @@ +default: false + +# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md001.md +MD001: true + +# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md003.md +MD003: + style: "consistent" + +# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md004.md +MD004: + style: "consistent" + +# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md005.md +MD005: true + +# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md007.md +MD007: + indent: 4 + +# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md009.md +MD009: true + +# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md010.md +MD010: true + +# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md011.md +MD011: true + +# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md012.md +MD012: true + +# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md014.md +MD014: true + +# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md018.md +MD018: true + +# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md019.md +MD019: true + +# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md020.md +MD020: true + +# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md021.md +MD021: true + +# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md022.md +MD022: true + +# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md023.md +MD023: true + +# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md024.md +MD024: + siblings_only: true + +# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md025.md +MD025: true + +# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md026.md +MD026: true + +# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md027.md +MD027: true + +# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md028.md +MD028: true + +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md029.md +MD029: + style: "ordered" + +# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md030.md +MD030: + ul_single: 1 + ol_single: 1 + ul_multi: 3 + ol_multi: 2 + +# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md031.md +MD031: true + +# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md032.md +MD032: true + +# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md034.md +MD034: true + +# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md035.md +MD035: true + +# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md036.md +MD036: true + +# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md037.md +MD037: true + +# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md038.md +MD038: true + +# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md039.md +MD039: true + +# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md040.md +MD040: true + +# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md042.md +MD042: true + +# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md045.md +MD045: true + +# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md046.md +MD046: + style: "fenced" + +# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md047.md +MD047: true + +# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md048.md +MD048: + style: "backtick" + +# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md049.md +MD049: + style: "asterisk" + +# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md050.md +MD050: + style: "consistent" + +# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md051.md +MD051: true + +# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md053.md +MD053: true + +# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md054.md +MD054: true + +# MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md055.md +MD055: + style: "no_leading_or_trailing" + +# MD056/table-column-count : Table column count : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md056.md +MD056: true diff --git a/.markdownlintrc b/.markdownlintrc deleted file mode 100644 index ea337115..00000000 --- a/.markdownlintrc +++ /dev/null @@ -1,33 +0,0 @@ -{ - // Enable all markdownlint rules - "default": true, - - // Disable line length check - "MD013": false, - - // Set Ordered list item prefix to "ordered" (use 1. 2. 3. not 1. 1. 1.) - "MD029": { "style": "ordered" }, - - "MD030": { "ul_multi": 3, "ol_multi": 2 }, - - // Set list indent level to 4 which Python-Markdown requires - "MD007": { "indent": 4 }, - - // Code block style - "MD046": { "style": "fenced" }, - - // Multiple headings with the same title - "MD024": { "siblings_only": true }, - - // Allow inline HTML - "MD033": false, - - // First line heading - "MD041": false, - - // Disable named references validation - "MD052": false, - - // Table pipe style - "MD055": { "style": "no_leading_or_trailing" } -} diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 383ce193..25026974 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/docs/user-guide/choosing-your-theme.md @@ -26,14 +26,14 @@ every feature of MkDocs. In addition to the default [theme configuration options][theme], the `mkdocs` theme supports the following options: -* __`highlightjs`__: Enables highlighting of source code in code blocks using +* **`highlightjs`**: Enables highlighting of source code in code blocks using the [highlight.js] JavaScript library. Default: `True`. -* __`hljs_style`__: The highlight.js library provides 79 different [styles] +* **`hljs_style`**: The highlight.js library provides 79 different [styles] (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: `github`. -* __`hljs_languages`__: By default, highlight.js only supports 23 common +* **`hljs_languages`**: By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. ```yaml @@ -45,10 +45,10 @@ supports the following options: - rust ``` -* __`analytics`__: Defines configuration options for an analytics service. +* **`analytics`**: Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the `gtag` option. - * __`gtag`__: To enable Google Analytics, set to a Google Analytics v4 + * **`gtag`**: To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the `G-` format. See Google's documentation to [Set up Analytics for a website and/or app (GA4)][setup-GA4] or to [Upgrade to a Google Analytics 4 property][upgrade-GA4]. @@ -63,7 +63,7 @@ supports the following options: When set to the default (`null`) Google Analytics is disabled for the site. -* __`shortcuts`__: Defines keyboard shortcut keys. +* **`shortcuts`**: Defines keyboard shortcut keys. ```yaml theme: @@ -79,19 +79,19 @@ supports the following options: available on all keyboards. You may use to determine the key code for a given key. - * __`help`__: Display a help modal that lists the keyboard shortcuts. + * **`help`**: Display a help modal that lists the keyboard shortcuts. Default: `191` (?) - * __`next`__: Navigate to the "next" page. Default: `78` (n) + * **`next`**: Navigate to the "next" page. Default: `78` (n) - * __`previous`__: Navigate to the "previous" page. Default: `80` (p) + * **`previous`**: Navigate to the "previous" page. Default: `80` (p) - * __`search`__: Display the search modal. Default: `83` (s) + * **`search`**: Display the search modal. Default: `83` (s) -* __`navigation_depth`__: The maximum depth of the navigation tree in the +* **`navigation_depth`**: The maximum depth of the navigation tree in the sidebar. Default: `2`. -* __`nav_style`__: This adjusts the visual style for the top navigation bar; by +* **`nav_style`**: This adjusts the visual style for the top navigation bar; by default, this is set to `primary` (the default), but it can also be set to `dark` or `light`. @@ -101,7 +101,7 @@ supports the following options: nav_style: dark ``` -* __`locale`__{ #mkdocs-locale }: The locale (language/location) used to +* **`locale`**{ #mkdocs-locale }: The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. @@ -123,10 +123,10 @@ two levels of navigation are supported. In addition to the default [theme configuration options][theme], the `readthedocs` theme supports the following options: -* __`highlightjs`__: Enables highlighting of source code in code blocks using +* **`highlightjs`**: Enables highlighting of source code in code blocks using the [highlight.js] JavaScript library. Default: `True`. -* __`hljs_languages`__: By default, highlight.js only supports 23 common +* **`hljs_languages`**: By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. ```yaml @@ -138,9 +138,9 @@ theme supports the following options: - rust ``` -* __`analytics`__: Defines configuration options for an analytics service. +* **`analytics`**: Defines configuration options for an analytics service. - * __`gtag`__: To enable Google Analytics, set to a Google Analytics v4 + * **`gtag`**: To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the `G-` format. See Google's documentation to [Set up Analytics for a website and/or app (GA4)][setup-GA4] or to [Upgrade to a Google Analytics 4 property][upgrade-GA4]. @@ -154,31 +154,31 @@ theme supports the following options: When set to the default (`null`) Google Analytics is disabled for the - * __`anonymize_ip`__: To enable anonymous IP address for Google Analytics, + * **`anonymize_ip`**: To enable anonymous IP address for Google Analytics, set this to `True`. Default: `False`. -* __`include_homepage_in_sidebar`__: Lists the homepage in the sidebar menu. As +* **`include_homepage_in_sidebar`**: Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the `nav` configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: `True`. -* __`prev_next_buttons_location`__: One of `bottom`, `top`, `both` , or `none`. +* **`prev_next_buttons_location`**: One of `bottom`, `top`, `both` , or `none`. Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`. -* __`navigation_depth`__: The maximum depth of the navigation tree in the +* **`navigation_depth`**: The maximum depth of the navigation tree in the sidebar. Default: `4`. -* __`collapse_navigation`__: Only include the page section headers in the +* **`collapse_navigation`**: Only include the page section headers in the sidebar for the current page. Default: `True`. -* __`titles_only`__: Only include page titles in the sidebar, excluding all +* **`titles_only`**: Only include page titles in the sidebar, excluding all section headers for all pages. Default: `False`. -* __`sticky_navigation`__: If True, causes the sidebar to scroll with the main +* **`sticky_navigation`**: If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: `True`. -* __`locale`__{ #readthedocs-locale }: The locale (language/location) used to +* **`locale`**{ #readthedocs-locale }: The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. @@ -189,7 +189,7 @@ theme supports the following options: See the guide on [localizing your theme] for more information. -* __`logo`__: To set a logo on your project instead of the plain text +* **`logo`**: To set a logo on your project instead of the plain text `site_name`, set this variable to be the location of your image. Default: `null`. ## Third Party Themes