markdownlint

• 4 minutes to read
 • 4 minutes to read

What is markdownlint

markdownlint is an extension to VS Code that encourages standards and consistency for Markdown. It is available directly from the VisualStudio marketplace or via the Docs Authoring Pack extension.

Rules

The rules have a number and an alias. For example MD029/ol-prefix.

Our custom rule-set

We have tailored the linting rules to align with our Markdown style guide. The custom configuration is located in .markdownlint.yaml.

Note

Don't alter the rules without discussing it with the DX team.

Use

When you edit a Markdown (.md) file in VS Code with this extension installed, you get visual warnings in the editor for lines that violate a rule.

Example:

Warning from markdownlint in VS Code -screenshot

Here, the wavy underline indicates a problem with list numbering.

You can hover to find out more about the problem:

Hovering warning from markdownlint in VS Code-screebshot

Here we see that it is rule MD029 that is violated and that the list prefix on line 27 should be 3 and not 4.

You now have a few options for how to proceed:

  • Edit the Markdown manually.
  • Select Quick Fix and then select to fix all violations in the file.

Quick fix warning from markdownlint in VS Code-screebshot

Tip

Click the first link in the Quick Fix dialog to read more about the rule.

Special cases

In some cases, we deliberately deviate from the rules by manually turning a rule off for a single line, a group of lines, or an entire file.

You will see this as HTML comments inside the Markdown files like this:

<!-- markdownlint-disable-next-line MD001 MD005 -->

Leave these comments as is. We need them to establish a valid baseline for the repo.

Noteworthy exceptions:

  • Because all include files are fragments, the first line must be <!-- markdownlint-disable-file MD041

  • Because tabbed content uses a specific syntax, rule MD051 must be disabled like this:

    <!-- markdownlint-disable MD051 -->
### [NetServer Core](#tab/core)

Contents of core tab

### [NetServer Web Services](#tab/ws)

Contents of ws tab

***
<!-- markdownlint-restore -->

  • Excessively long headings that can't be shortened must be prefixed with <!-- markdownlint-disable-next-line MD013 -->

  • When list numbering is part of an include, you might need to handle numbering before/after the included file yourself. <!-- markdownlint-disable-file MD029 -->

There are a few more, mostly pertaining to API documentation and code examples. If in doubt, search for the rule ID (such as MD029) in the repo source and you'll find examples of how to handle it. Ask if you have questions.

Command-line linting

You can optionally install markdownlint-cli, a command-line interface that allows you to do bulk linting. This is useful for bulk editing but it can also be added to a build pipeline as automatic testing.

Install:

npm install -g markdownlint-cli

Use:

markdownlint -f -i *.cs *.xml --disable MD013 MD041 -c  .markdownlint.yaml PATH
  • -f will automatically fix problems that have a defined fix, for example, whitespace
  • -i ignores whatever follows, in this case, all cs and XML files. To omit API from the run, add api/ to the path.
  • --disable turns off the listed rules
  • -c specifies the markdownlint config file. In this case, we use the one inside the superoffice-docs repo

See GitHub issue 373 regarding why we exclude rules MD013 and MD041.