Ensure consistent Markdown style with Markdownlint

by Andreas Mosti

Markdown is great. It's easy and flexible, and provides a good markup language even non-technical people can understand and enjoy. But, that flexibility and customizability can come at a cost. Document buildup can be done in many ways, and it can be hard to ensure consistency when working with multiple documents and contributors.

I like to think of markup languages as code, and most code deserves a good style guide. Markdownlint is a good alternative.

markdownlint provides a nice set of standard rules when writing markdown, like:

  • Heading levels should only increment by one level at a time
  • Lists should be surrounded by blank lines
  • First line in file should be a top level heading
  • No empty links
  • No trailing spaces
  • No multiple consecutive blank lines

just to name a few. It also ensures consistency in headers, like

My Heading  
===

vs.

# My Heading

Another smart rule is ensuring language description when writing code blocks.

The VSCode extension shows a squiggle when a code block is missing a language description:

If some rules don't fit your style or project, they can be override with a .markdownlint.json file:

{
    "MD013": false, // Disable line length rule.  
    "MD024": false // Allow Multiple headings with the same content.
}

The easiest way to start using markdownlint is to install the extension for VSCode or Atom (RIP Atom), or integrated with builds using Grunt, Github Actions etc. My preferred way is directly with the markdownlint-cli.

For my Coffee recipes I use a simple container with Github Actions:

If any rules are broken, it breaks the build.