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 rule sets of the two.
As mentioned above I am primarily using DavidAnson/markdownlint, so the below set of rules are based on that implementation.
This rule has the label/name: MD004, do see the documentation.
I prefer to have my lists using the - for indicating elements. Consistent formatting makes it easier to read and understand documentation. Markdown does allow for a variation of styles, for example: * (asterisk).
Example:
- item1
- item2
- item3This rule has the label/name: MD049, do see the documentation.
I prefer to use _ for emphasis, again Markdown allow for varies characters for indicating emphasis, for example: * (asterisk). Sticking to one, makes it easier for me, when editing and this rule makes it easier to be consistent in writing style.
Example:
_this is emphasized, but is cursive and does not stand out in the same manner as bold IMHO_This rule has the label/name: MD050, do the the documentation.
I use * to indicate importance (bold), I know this should be called emphasis, but the emphasis, which is cursive, I use for that quotes and terms that are special, where some people would use quotes.
**this is emphasized as strong/bold**Markdown again allows for a variety of characters, like _ (underscore).