Multiple top level headings don't follow markdown linting guidelines

[Emilio Martinez-Cordero]

This project relies on Markdown, which makes it really easy to use, especially because it established a very short and simple set of rules to make it work with PRs in Bitbucket. However, one of those rules happens to contradict a fairly common guideline followed across multiple document standards: avoiding the use of multiple top level headers.

In the case of Markdown, for example, it is usually enforced by linting: "MD025 - Multiple top level headers in the same document". In the case of HTML, for example, it's noted within the Web Content Accessibility Guidelines: https://www.w3.org/TR/WCAG20-TECHS/G141.html

That said, of course, it contradicts guidelines such as .

Proposal

Do not use the top level headers as categories but instead have that be the level 2 headers. The third level headers can be used for the rules respectively.