Style Guide #

Semantic Line Breaks #

It is encouraged to use Semantic Line Breaks when writing for the handbook. This improves the readability of source files and make diffs clearer. The Semantic Line Breaks specification explains the rules and reasoning. The most important rules are,

• A semantic line break MUST occur after a sentence, as punctuated by a period (.), exclamation mark (!), or question mark (?).
• A semantic line break SHOULD occur after an independent clause as punctuated by a comma (,), semicolon (;), colon (:), or em dash (—).
• A semantic line break MAY occur after a dependent clause in order to clarify grammatical structure or satisfy line length constraints.

Markdown #

Whenever possible, the handbook’s prose should be written in Markdown rather than HTML. However, it is completely reasonable use HTML when it is needed. When it is advantageous, data should be stored in data files and processed using shortcodes rather than presented in raw Markdown.

Style Enforcement #

Markdown styling is enforced using the markdownlint tool, using the style rules in .mdl_style.rb . An explanation of the rules can be found here.

Markdown linting is performed on all pull requests made to the handbook repository, as described in the Continuous Integration section.

If you wish to lint locally, the repository contains a pre-commit hook to do this, described in the Making Changes section.