Introduce markdown linter
It is really easy to write markdown, therefore it is really easy to make mistakes.
One of the most common mistakes I see on our docs website, is wrong heading levels. You can spot them quite easily in the navigation (currently live on https://docs.gitlab.com/ee/api/README.html):
In the past I've used the rather good remark-lint which lints markdown for errors. In the above example it would print for example:
107:1-107:20 warning Heading levels should increment by one level at a time heading-incrementIt has many configurable rules, a more strict setting preset can be found in remark-preset-lint-markdown-style-guide which tries to enforce the Markdown style guide.
In a first iteration it would probably be enough to enable rules which detect that really break our layout e.g. the wrong heading increment.
What do you think? Is this something we should explore? It would save you probably a lot of easy nitpick comments in the future and prevent the people from writing bad markdown!