Today I Learned: collection of notes, tips and tricks and stuff I learn from day to day working with computers and technology as an open source contributor and product manager

View project on GitHub

Use Markdownlint

Markdown has become my preferred way to write documentation. I use it for the documentation for open source projects, like READMEs, Change Logs etc. In additional to that I use if for longer technical specifications, since it is so simple to work with and Markdown is so easy to use it lets me focus on the content I want to write.

Writing to many different documents and with the focus on content I sometimes make mistakes in my Markdown, but since Markdown is well formatted, it is actually possible to parse it and say something about the formatting - and here Markdown linters can help you.

I am unclear on the story behind the Markdown linters I have found, but it seems as if the first implementation was in Ruby, the project is markdownlint/markdownlint and offers the executable mdl.

A newer alternative is the Markdown linter implemented in Node, this project is DavidAnson/markdownlint. The Node implementation does not hold it’s own executable, there you have to use the executable markdownlint implemented in igorshubovych/markdownlint-cli.

Both implementations implement a set of rules Ruby implementation and Node implementation respectively.

This documentation is nice to have close at hand when you get started.

I wrote up a blog post where I compare the rulesets of the two.