Switch to an explicit markdownlint config

Based on https://github.com/DavidAnson/markdownlint/blob/v0.33.0/schema/.markdownlint.yaml
lakamson · Jan 29, 2024 · 953839f · 953839f
1 parent 369dcc0
commit 953839f
Show file tree

Hide file tree

Showing 3 changed files with 173 additions and 59 deletions.
diff --git a/.markdownlint.yaml 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
diff --git 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 <https://keycode.info/> 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` (&quest;)
 
-    *   __`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