Add a Markdown linter for all .md files #10787
Description
In addition to Prettier (see #10402) it would be great to enable a linter that checks if the markdown makes sense.
There already is a markdown linter in CI, but it is currently enabled for meta docs only. #7146 is a stalled PR that tried to enable it for all .md files.
Not all files currently comply with all md-lint rules. The following configuration would currently pass CI, but we should enable many of these rules (and potentially others not listed below).
To test, run npx markdownlint-cli . -i node_modules -i LICENSE.md and add .markdownlint.json to the content folder. Remove some of the lines below to see how they would fail.
{
"default": true,
"MD001": false, // Heading levels should only increment by one level at a time
"MD004": false, // Consistent unordered list style
"MD005": false, // Inconsistent indentation for list items at the same level
"MD007": false, // Unordered list indentation
"MD009": false, // Trailing spaces
"MD010": false, // Hard tabs
"MD011": false, // Reversed link syntax
"MD012": false, // Multiple consecutive blank lines
"MD013": false, // Line length
"MD014": false, // Dollar signs used before commands without showing output
"MD019": false, // Multiple spaces after hash on atx style heading
"MD022": false, // Headings should be surrounded by blank lines
"MD023": false, // Headings must start at the beginning of the line
"MD024": false, // Multiple headings with the same content
"MD026": false, // Trailing punctuation in heading
"MD027": false, // Multiple spaces after blockquote symbol
"MD028": false, // Blank line inside blockquote
"MD029": false, // Ordered list item prefix
"MD030": false, // Spaces after list markers
"MD031": false, // Fenced code blocks should be surrounded by blank lines
"MD032": false, // Lists should be surrounded by blank lines
"MD033": false, // Inline HTML
"MD034": false, // Bare URL used
"MD035": false, // Horizontal rule style
"MD036": false, // Emphasis used instead of a heading
"MD037": false, // Spaces inside emphasis markers
"MD038": false, // Spaces inside code span elements
"MD039": false, // Spaces inside link text
"MD040": false, // Fenced code blocks should have a language specified
"MD042": false, // No empty links
"MD045": false, // Images should have alternate text (alt text)
"MD046": false, // Code block style
"MD047": false // Files should end with a single newline character
}Tasks (roughly):
- Fix files so that we can enable more MD rules
- Document how to use markdownlint-cli locally (add
yarn content mdlintcommand?) - Also add a way to use the
--fixoption easily (and document it, too) - Update PR authoring guide / contribution docs
- Make sure CI reports linting errors in a beginner friendly way (should they become part of the bot message?)
- Make sure markdownlint interacts sensibly with Prettier (and eslint)
- Enable markdownlint-cli for all .md files