Ensure consistent Markdown style with Markdownlint
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 consitency 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
to name a few. It also ensures concistensy in headers, like:
My Heading
===
vs.
# My Heading
Another smart rule is ensuring language description when writing code blocks.
If some rules don't fit your style or project, they can be overrided 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 extention for VSCode or Atom, or integrated with builds using Grunt or markdownlint-cli.
For my Coffee recipes I use a simple container with Travis:
sudo: required
language: generic
services:
- docker
script:
- docker run --rm -v $(pwd):/usr/src/app/files -it andmos/markdownlint *.md
If any rules are broken, it breaks the build.