ci: use markdownlint to enforce mkdocs compatibility

mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab
for detecting indentation levels, including ordered- and
unordered-lists. Since we cannot easily change the renderer, begin using
a markdown linter in CI that will fail if official docs do not adhere to
the spacing rules.

As a starting point, the markdownlint config does not begin with the
default set of checks, which might overwhelm attempts to fix them.
Instead, focus on list-tab-spacing rules and a few other highly useful
checks.

Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>

.github/workflows/docs-check.yml

@@ -36,6 +36,11 @@ jobs:
         with:
           python-version: 3.9
 
+      - uses: articulate/actions-markdownlint@v1
+        with:
+          config: .markdownlint-config.json
+          files: ./Documentation
+
       - name: Check helm-docs
         run: make check-helm-docs
       - name: Check docs

.markdownlint.yaml

@@ -0,0 +1,34 @@
+# Rules ref: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# no default rules enabled
+default: false
+extends: null
+
+# all list items must be indented at the same level
+list-indent: true
+
+ul-indent:
+  # mkdocs requires 4 spaces for tabs
+  indent: 4
+
+no-hard-tabs:
+  # mkdocs requires 4 spaces per tab
+  spaces_per_tab: 4
+  code_blocks: false # allow tabs in code blocks
+
+# this rule also ensures that code blocks don't "break" lists
+ol-prefix:
+  # allow all-1-lists, or fully-numbered lists
+  style: one_or_ordered
+
+# mkdocs requires blank lines around lists
+blanks-around-lists: true
+
+# do not allow duplicate headings
+no-duplicate-heading: true
+
+# validate links to headings within a doc
+link-fragments: true
+
+# require single trailing newline in docs
+single-trailing-newline: true

.vscode/settings.json

@@ -16,4 +16,9 @@
     "editor.defaultFormatter": "ms-python.black-formatter",
     "editor.formatOnSave": true
   },
+  "[markdown]": {
+    "editor.tabSize": 4,
+    "editor.detectIndentation": false,
+  },
+  "markdown.extension.list.indentationSize": "inherit"
 }