ci: use markdownlint to enforce mkdocs compatibility

[BlaineEXE]

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:

- first bullet
- second bullet
    still second bullet
- third bullet

    has a paragraph
    of text inside

- last bullet

Checklist:

• Commit Message Formatting: Commit titles and messages follow guidelines in the developer guide.
• Reviewed the developer guide on Submitting a Pull Request
• Pending release notes updated with breaking and/or notable changes for the next minor release.
• Documentation has been updated, if necessary.
• Unit tests have been added, if necessary.
• Integration tests have been added, if necessary.

[BlaineEXE]

@travisn @parth-gr @galexrt related to this PR (and others) #13968 (comment)

mkdocs's yaml parser is adamant that they will not support 2-spaces-per-tab, and they require 4 spaces. Mkdocs devs are adamant that they won't support modifying the parser or this particular behavior. This means that our current docs will render fine in github/vscode, but not on the website.

The best way I could find to fix our docs without switching to something other than mkdocs is to do 2 things:

• set rook-project vscode configs to use 4 spaces per tab for markdown and to not "interpret" current spacing
• lint the docs using markdownlint

As of now, I haven't fixed any lint issues. I wanted to discuss and decide how to proceed from here before doing that.

[travisn]

Are the spaces between the * and first word intentional? That doesn't seem expected to me.

[BlaineEXE]

Yes. We can chat more about some of the weird things that this is going to be requiring like this one.

[BlaineEXE]

markdownlint really isn't all that great as a tool. It particularly has gaps in requiring 4-space tabs throughout the full document. It will only force it on list items but not the paragraph conentents of list items.

Rook uses a lot of lists with multiple paragraphs and code blocks inside lists, which mkdocs won't render properly unless those are indented very exactly.

I had to find something else that we could use to help fill in this particular gap. The tool called "Prettier" was commonly recommended for markdown, and I found that using its --tab-width=4 option helps to ensure that paragraph contents (especially code blocks) are spaced appropriately to be rendered by mkdocs and/or flagged as an error by markdownlint.

The downside is that Prettier is VERY opinionated. It requires using - for bullet points, and it requires that bullet points adhere to the tab-width option. It also doesn't like the standard callout/admonition syntax and requires a newline between the callout header and text.

IMO, this is certainly not ideal, but it is much more usable than having docs that render properly on github but silently fail (and create subtle bugs) in user-facing docs.

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @BlaineEXE please rebase it. https://rook.io/docs/rook/latest/Contributing/development-flow/#updating-your-fork

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @BlaineEXE please rebase it. https://rook.io/docs/rook/latest/Contributing/development-flow/#updating-your-fork

[BlaineEXE]

Latest updates (from Friday)

• I went through the docs that had merge conflicts (3-4 of them) and made sure things were formatted correctly for the PR
• I found out that markdownlint supports custom lint rules, so I made one to ensure that our admonitions/callouts are formatted correctly. This actually caught 3 cases where I hadn't captured the formatting correctly, and it will mean that we don't have to be as mindful about checking that in PR reviews

For consideration:

The main reason why I also included 'Prettier' was because markdownlint didn't have a good way of checking that all lines are indented to a 4-space boundary (for mkdocs)

Now that I know how to write custom markdownlint modules, it would be fairly simple to write one to ensure this 4-space boundary

This would allow us to get rid of 'Prettier' if we want, with some pros/cons:

• Pros
  • admonitions/callouts don't need the extra newline between header and body, which we use as a workaround for Prettier
  • when updating a doc, Prettier might sometimes alter formatting to be something unintended if it misinterprets a typo (like bullets to underscores), so getting rid of it could help
• Cons
  • Prettier is really nice for automatically (in VScode) turning any typed markdown into the form needed for mkdocs, without the need for users to run mardownlint or wait for CI, and we'd lose that
  • Prettier formats docs with compatibility in mind (e.g., auto-escaping the asterisk in myglob* to myglob\* to ensure the asterisk isn't misinterpreted as intent to italicize), and we'd lose that potential benefit

[travisn]

Are you saying you created that custom rule locally? Or it's part of this PR and we will have it going forward?

If we already have the custom linter, maybe it would be good to get rid of prettier if we don't need it. But whatever you think is simplest to get this done and not spend too much more time on it.

[travisn]

That local preview is working for you?