We should add a markdown linter with the corresponding rules to Travis CI to enforce standards and consistency for Markdown files to help with reading and writing files with markdown markup. It comes with 45 pre-packaged rules, which can be adjusted to fit your needs. E.g line-length, no-bare-urls or no-empty-links.
In the beginning a small defined set of rules should be applied which can later be extended as markdown markup quality improves.
Out of the 45 pre-packaged rules the following have been activated:
MD004: unordered list style
This rule is triggered when the symbols used in the document for unordered list items do not match the
configured unordered list style. The style is set to "consistent"
MD005: inconsistent indentation for list items at the same level
This rule is triggered when list items are parsed as being at the same level, but don't have the same indentation.
MD006: consider starting bulleted lists at the beginning of the line
This rule is triggered when top level lists don't start at the beginning of a line
MD007: unordered list indentation
This rule is triggered when list items are not indented by the configured number of spaces. The indent is
set to "4", because python-markdown requires 4 spaces of indentation. See https://python-markdown.github.io/#differences
This rule is triggered when there are lines that are longer than the configured line length. This rule has
an exception where there is no whitespace beyond the configured line length. This allows to still include
items such as long URLs without being forced to break them in the middle. There is the option to exclude
this rule for code blocks, tables, or headers. To do so, set the code_blocks, tables, or headers parameter(s) to false.
The line length is set to "120" and code blocks and tables are not included in this rule, so they are allowed
to exceed the limit of 120. Headers are included in this rule, because headers should be reasonable short.
MD018: require space after hash on atx style header
MD019: prohibit multiple spaces after hash on atx style header
MD025: prevent multiple top level headers in the same document
MD042: no empty links
MD045: Images should have alternate text (alt text)
This rule is triggered when an image is missing alternate text (alt text) information. Alternate text is
important for accessibility, describing the content of an image for people who may not be able to see it.