Add Markdown linting for the docs

[SeanKilleen]

One of my initial goals for #5309 was to implement both spellcheck and markdown linting for the docs, but there were just too many changes there. Best to go one bite at a time.

Game Plan

• Examine markdown linting with some standard rules in place from NUnit
• Enumerate a list of thematic changes here in this issue
• Tackle all the linting changes in thematic PRs
• (Markdown linting: build steps and last fixes #5345) Add markdownlint rules and Azure DevOps task to run the linting (which should, if all goes well, pass shortly thereafter)

My Approach

• Create markdownlint settings files (.markdownlintrc and .markdownlint.json)
• Disable all rules ("default": false in the config)
• Enable one tag or rule at a time
• Work through those items in a PR -- where possible, using VSCode tooling to apply fixes per file.

Hoping this will keep things consistent and thematic and therefore easier to review and discuss.

Local Tooling

• npm install -g markdownlint-cli
• markdownlint "docs/**/*.md"

Items to Tackle

Themes / tags -- taken from markdownlint site -- I may break these up smaller as warranted:

• ✅ Prerequisite: spell checking (Add spellcheck for docs #5309)
• ✅ (no issues reported) accessibility - MD045
• ✅ (Markdown linting: "atx" and "atx-closed" categories #5313) atx - MD018, MD019
• ✅ (Markdown linting: "atx" and "atx-closed" categories #5313) atx_closed - MD020, MD021
• ✅blank_lines - MD012, MD022, MD031, MD032, MD047
  • Markdown linting: Blank lines around headers (MD022) #5314
  • Markdown linting: blank lines around fences (MD031) #5317
  • Markdown linting: rest of the blank lines rules #5319
• ✅(Markdown linting: Blockquotes #5320) blockquote - MD027, MD028
• ✅ (covered by other PRs) bullet - MD004, MD005, MD006, MD007, MD032
• ✅ (Covered in other PRs) code - MD014, MD031, MD038, MD040, MD046, MD048
• ✅(Markdown linting: Convert emphasis to headings #5342) emphasis - MD036, MD037
• ✅ (Markdown linting: Replace hard tabs with 4 spaces (MD010) #5315) hard_tab - MD010
• ✅ (Markdown linting: Headings / Headers #5343) headers - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043
• ✅ (Markdown linting: Headings / Headers #5343) headings - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043
• ✅ (no issues reported) hr - MD035
• ✅(Markdown linting: HTML in markdown #5324) html - MD033
• ✅ (no issues reported) images - MD045
• ✅(covered by other PRs) indentation - MD005, MD006, MD007, MD027
• ✅ (Markdown linting: Add languages to code blocks #5322) language - MD040
• ✅line_length - MD013 (ignored)
• ✅ (no issues reported) links - MD011, MD034, MD039, MD042
• ✅ (Markdown linting: spacing around ordered lists #5323) ol - MD029, MD030, MD032
• ✅(Markdown linting: Unordered Lists + MD019 for headers #5330) spaces - MD018, MD019, MD020, MD021, MD023
• ✅ (no issues reported) spelling - MD044
• ✅(Markdown linting: Unordered Lists + MD019 for headers #5330) ul - MD004, MD005, MD006, MD007, MD030, MD032
• ✅ (Markdown linting: Brackets around bare URLs #5316) url - MD034
• ✅ (Markdown linting: Whitespace #5332) whitespace - MD009, MD010, MD012, MD027, MD028, MD030, MD037, MD038, MD039

[SeanKilleen]

A side note on this -- I'm explaining my rationale, process, and tooling here because I think others may want to get involved and this is a relatively straightforward thing to work on. If anyone is interested, tag me here and I'll be happy to give you any walkthrough to get you up and running to contribute to the effort.

[sean-gilliam]

Great stuff man

[SeanKilleen]

Once the 5 outstanding PRs are merged, we can move onto the next batch. I think there will be too many conflicts to try to proceed with the other items in parallel.

[SeanKilleen]

At the next stopping point. I think Once the 3 outstanding PRs are merged, can continue onto the following topics.

[SeanKilleen]

OK, we're in a pretty good place here.

I think once the last linting PR on headings is merged, I should be able to do the last PR which will introduce the actual checking, the ignore files, etc.

[SeanKilleen]

Last PR! 🎉 Everything looks to be in order, so I think this issue will be closed entirely soon.

[Aaronontheweb]

Well done.