Add markdown one-line-per-line layout rule (#41)

* Create markdown specification document This adds a markdown specification document. Please see exercism/configlet#150 (comment) for the rationale of these choices. * Update contributing/standards/markdown.md Co-authored-by: Sascha Mann <[email protected]> * Add markdown one-line-per-line layout rule * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <[email protected]> * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <[email protected]> * Add linting rules (#45) * Add linting rules * Update contributing/standards/markdown.md Co-authored-by: Erik Schierboom <[email protected]> Co-authored-by: Erik Schierboom <[email protected]> Co-authored-by: Sascha Mann <[email protected]> Co-authored-by: Erik Schierboom <[email protected]>
exercism · Feb 5, 2021 · 6e74b46 · 6e74b46
1 parent aa78d01
commit 6e74b46
Showing 1 changed file with 34 additions and 3 deletions.
diff --git a/contributing/standards/markdown.md b/contributing/standards/markdown.md
@@ -2,14 +2,45 @@
 
 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.
+Some of the rules in this document are not yet implemented across all of Exercism. 
 We welcome PRs to fix them.
-All rules are being added to our CI and linting tools.
+All rules are being added to our CI and linting tools, and should be adhered to for new changes.
 
 ## Headings
 
 - All files must start start with a level-1 heading (`# Some heading text`).
 - Level-1 headings exist purely for consuming on GitHub or equivalent.
 - If the file is rendered by 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 `####`)
+- 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.
+
+## Layout
+
+### One sentence per line
+
+Paragraphs should be laid at using one sentence per line. The [Ascii Doctor docs][asciidoctor] explain the logic of this clearly.
+
+For example, a single paragraph should be laid out as follows:
+```
+Exercism has been designed, engineered and built by thousands of very talented individuals.
+Nearly everything with Exercism has been debated, discussed and rewritten many times.
+Exercism is a very intentional product - things are there because they've been designed to be there, and things are often left out because they've been designed to be left out.
+```
+
+## Inline HTML
+
+- Inline HTML is allowed, but should be used sparingly
+- Always use native markdown alternatives if available (e.g. use `# ...` rather than `<h1>...</h1>`)
+
+## Linters
+
+There are various rules you can use to configure linters to meet this spec:
+- Enable [MD001](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md001---header-levels-should-only-increment-by-one-level-at-a-time)
+- Enable [MD002](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md002---first-header-should-be-a-top-level-header)
+- Use `atx` for [MD003](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md003---header-style)
+- Disable [MD013](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md013---line-length)
+- Disable [MD033](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md033---inline-html)
+
+---
+
+[asciidoctor]: https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line