Linting with Vale and markdownlint

• markdownlint - Markdown formatting
  • Documentation
  • See all markdownlint errors in a directory or tree
• Vale - Spelling, grammar, style
  • Style guides
    • Example
    • Customization
    • Spelling

markdownlint - Markdown formatting

markdownlint is available as a VS Code extension. Rules are customizable.

Documentation

• markdownlint documentation
• Enable and suppress rules by page or inline

Configuration file: .markdownlint.jsonc

Common rules for reference:

<!-- markdownlint-disable MD033 no inline html -->
<!-- markdownlint-enable MD033 -->
<!-- markdownlint-disable MD044 proper name for <word> -->
<!-- markdownlint-enable MD044 -->
<!-- markdownlint-disable-next-line MD028 no blanks in block -->
<!-- markdownlint-disable MD041 first line heading is h1 -->
<!-- markdownlint-disable MD024 no duplicate heading -->
<!-- markdownlint-disable MD001 headings increment one at a time -->

See all markdownlint errors in a directory or tree

Install the markdownlint CLI:

npm install -g markdownlint-cli

Run this command at the root of the documentation repo:

markdownlint 'articles/**/*.md' --config .markdownlint.JSONC

markdownlint-cli documentation and options

Vale - Spelling, grammar, style

Vale is available as a VS Code extension or as a standalone CLI. Catalyst is not using Vale Server. Rules are customizable.

Vale documentation

Configuration file: vale.ini

To run Vale without installing the VS Code extension: From the root of the documentation repo, run vale .vale.ini articles > linting.md

Style guides

This repo represents a custom style guide.

However, Microsoft, Google, Vale, Write Good, etc., offer Vale style guides. To lint against these or other guides, download them to vale-styles/{style-guide} and add the parent folder name to vale.ini (e.g., BasedOnStyles = Catalyst,Vale,Microsoft).

To customize application:

<!-- vale off -->

This is some text

more text here...

<!-- vale on -->

<!-- vale Style.Rule = NO -->

This is some text

<!-- vale Style.Rule = YES -->

Based on this tree in the repo...

root
  Docs
    vale-styles
      Linting
        All.yml

...a style rule would be Linting.All.

Example

<!-- vale Linting.Spelling = NO -->
Text
<!-- vale Linting.Spelling = YES -->

Source

Customization

To preserve the integrity of the .yml files in downloaded styles, copy any .yml file you want to customize into the custom vale-styles/Linting directory. For example, if you don't like a word a .yml file in the Microsoft style checks for, copy that .yml file to the Linting directory and remove the term. Then you can exclude the original .yml style in vale.ini (e.g., Microsoft.HeadingAcronyms = NO).

If you don't do it this way and, for example, Microsoft comes out with a new-and-improved style, you can't just replace the old Microsoft style files with the new ones, because you customized the original files.

Custom .yml rules can be created with Vale extension points.

Spelling

Ignore file: vale-styles/Linting/spelling-ignore.txt