Create markdown specification document

This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices.
exercism · Feb 3, 2021 · 636cbb2 · 636cbb2
1 parent acebb70
commit 636cbb2
Showing 1 changed file with 14 additions and 0 deletions.
diff --git a/contributing/standards/markdown.md b/contributing/standards/markdown.md
@@ -0,0 +1,14 @@
+# Markdown Specification
+
+The following is the way that all Markdown files within Exercism should be structured.
+
+Some of the rules in this document are not yet implemented across Exercism. 
+We welcome PRs to fix them.
+All rules are being added to our CI and linting tools.
+
+## Headings
+- All files must start start with a level-1 heading (`# Some heading text`). 
+- Level-1 headings exist purely for consuming on GitHub or equivelent.
+- If the file is rendered on by the Exercism (e.g. displayed on the website, rendered via the CLI), this heading will be removed, and a contextual heading will be inserted.
+- No heading may decend a level greater than one below the previous (e.g. `##` may only be followed by `###`, not `####`)
+- Beyond the single level-1 (`#`) heading, only level-2 (`##`), level-3 (`###`) and level-4 (`####`) headings may be used.