Provide a markdown styleguide

[gwarf]

In order to have a clear markdown styleguide that we can enforce using automated tools.

Hugo is using goldmark to parse and render markdown.
It's compliant with CommonMark.
GitHub Flavored Markdown is based on CommonMark.

So we need:

• a style guide compliant with CommonMark
• a linter able to enforce this when testing
• ideally an auto formatter that can be used with VIM and IDE

Some style guides and documentation about markdown:

• https://github.github.com/gfm/
• https://spec.commonmark.org/
• https://github.com/carwin/markdown-styleguide (could make a good basis for our style guide if we don' t find a perfect one already existing)
• https://daringfireball.net/projects/markdown/
• https://cirosantilli.com/markdown-style-guide/
• https://guides.github.com/features/mastering-markdown/
• https://markdown-guide.readthedocs.io/en/latest/basics.html

Some linters:

• https://github.com/prettier/prettier/ (can do autoformat, but not meant to be configurable)
• https://github.com/remarkjs/remark-lint (really configurable, with a configuration for https://cirosantilli.com/markdown-style-guide)
• https://github.com/markdownlint/markdownlint (AKA mdl gem, currently in use with Travis)
• https://github.com/DavidAnson/markdownlint/ (similar to mdl, but in nodejs)

[andrea-manzi]

too many options:-)
this one looks quite similar to what we have now https://github.com/carwin/markdown-styleguide, ( that you try to enforce manually:-)) , and if we can keep using the linter we have now in travis would be better

[gwarf]

Yes this one is nice as it's quite short and simple, but I would like to be sure that we have a style guide covering the Markdown flavour/derivative that we are using and that Hugo is using.
For the linter we need to be sure that it will be able to enforce our style guide, maybe mdl/markdownlint will be able, maybe not...
I've also tried to edit/simplify a bit the first post.