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.

markdownlint also has some gaps in its abilities that allow common Rook
doc issues to pass acceptance. However, it allows creating custom
linting plugins. Create 2 such linting plugins to check 2 things:

- all doc lines (except code blocks) must be aligned to a 4-space
  boundary, without exception. This ensures that markdown will render
  correctly with mkdocs. This unfortunately makes it possible to create
  lists that are internally aligned strangely.
- admonitions must all follow the same format of
  ```
  !!! header
      body
  ```

For the strange lists, this is allowed and renders correctly, but it
looks strange:

```md
- first bullet
- second bullet
    still second bullet
- third bullet

    has a paragraph
    of text inside

- last bullet

Signed-off-by: Blaine Gardner <[email protected]>

.markdownlint-cli2.cjs

@@ -0,0 +1,48 @@
+module.exports = {
+  "config": {
+    "default": false, // no default rules enabled
+    "extends": null, // no default rules enabled
+    "list-indent": true, // all list items must be indented at the same level
+    "ul-indent": {
+      "indent": 4, // mkdocs requires 4 spaces for tabs
+    },
+    "no-hard-tabs": {
+      "spaces_per_tab": 4, // mkdocs requires 4 spaces for tabs
+    },
+    "ol-prefix": {
+      // require fully-numbered lists. this rule helps ensure that code blocks in between ordered
+      // list items (which require surrounding spaces) don't break lists
+      "style": "ordered",
+    },
+    "blanks-around-lists": true, // mkdocs requires blank lines around lists
+    "blanks-around-fences": { // mkdocs requires blank lines around code blocks (fences)
+      "list_items": true, /// ... including in lists
+    },
+    "code-block-style": {
+      // do not allow implicit code blocks. ensure code blocks have fences so we know explicitly
+      // what will be rendered
+      "style": "fenced",
+    },
+    "fenced-code-language": {
+      // enforce code blocks must have language specified
+      // this helps ensure rendering is as intended, and it helps doc-wide searches for code blocks
+      language_only: true,
+    },
+    "no-duplicate-heading": true, // do not allow duplicate headings
+    "link-fragments": true, // validate links to headings within a doc
+    "single-trailing-newline": true, // require single trailing newline in docs
+    "no-multiple-blanks": {
+      // allow max 2 blank lines in markdown docs
+      "maximum": 2,
+    },
+
+    // custom rules for Rook!
+    "mkdocs-admonitions": true, // checking mkdocs admonitions format
+    "strict-tab-spacing": true, // enforce strict 4-space tabs for mkdocs
+
+  },
+ "customRules": [
+    "./tests/scripts/markdownlint-admonitions.js",
+    "./tests/scripts/markdownlint-tab-spacing.js",
+  ],
+};

.vscode/settings.json

@@ -16,4 +16,13 @@
     "editor.defaultFormatter": "ms-python.black-formatter",
     "editor.formatOnSave": true
   },
+  "[markdown]": {
+    "editor.tabSize": 4,
+    "editor.detectIndentation": false,
+  },
+  "markdown.extension.list.indentationSize": "inherit",
+  "markdownlint.lintWorkspaceGlobs": [
+    "Documentation/**/*.md",
+    "!Documentation/Helm-Charts",
+  ],
 }

Documentation/CRDs/Block-Storage/ceph-block-pool-crd.md

@@ -60,7 +60,7 @@ spec:
 This sample will lower the overall storage capacity requirement, while also adding redundancy by using [erasure coding](#erasure-coding).
 
 !!! note
-    This sample requires *at least 3 bluestore OSDs*.
+    This sample requires **at least 3 bluestore OSDs**.
 
 The OSDs can be located on a single Ceph node or spread across multiple nodes, because the [`failureDomain`](ceph-block-pool-crd.md#spec) is set to `osd` and the `erasureCoded` chunk settings require at least 3 different OSDs (2 `dataChunks` + 1 `codingChunks`).
 
@@ -202,12 +202,12 @@ stretched) then you will have 2 replicas per datacenter where each replica ends
 * `crushRoot`: The root in the crush map to be used by the pool. If left empty or unspecified, the default root will be used. Creating a crush hierarchy for the OSDs currently requires the Rook toolbox to run the Ceph tools described [here](http://docs.ceph.com/docs/master/rados/operations/crush-map/#modifying-the-crush-map).
 * `enableRBDStats`: Enables collecting RBD per-image IO statistics by enabling dynamic OSD performance counters. Defaults to false. For more info see the [ceph documentation](https://docs.ceph.com/docs/master/mgr/prometheus/#rbd-io-statistics).
 * `name`: The name of Ceph pools is based on the `metadata.name` of the CephBlockPool CR. Some built-in Ceph pools
-  require names that are incompatible with K8s resource names. These special pools can be configured
-  by setting this `name` to override the name of the Ceph pool that is created instead of using the `metadata.name` for the pool.
-  Only the following pool names are supported: `.nfs`, `.mgr`, and `.rgw.root`. See the example
-  [builtin mgr pool](https://github.com/rook/rook/blob/master/deploy/examples/pool-builtin-mgr.yaml).
+    require names that are incompatible with K8s resource names. These special pools can be configured
+    by setting this `name` to override the name of the Ceph pool that is created instead of using the `metadata.name` for the pool.
+    Only the following pool names are supported: `.nfs`, `.mgr`, and `.rgw.root`. See the example
+    [builtin mgr pool](https://github.com/rook/rook/blob/master/deploy/examples/pool-builtin-mgr.yaml).
 * `application`: The type of application set on the pool. By default, Ceph pools for CephBlockPools will be `rbd`,
-  CephObjectStore pools will be `rgw`, and CephFilesystem pools will be `cephfs`.
+    CephObjectStore pools will be `rgw`, and CephFilesystem pools will be `cephfs`.
 
 * `parameters`: Sets any [parameters](https://docs.ceph.com/docs/master/rados/operations/pools/#set-pool-values) listed to the given pool
     * `target_size_ratio:` gives a hint (%) to Ceph in terms of expected consumption of the total cluster capacity of a given pool, for more info see the [ceph documentation](https://docs.ceph.com/docs/master/rados/operations/placement-groups/#specifying-expected-pool-size)