Wiki writing guidelines
Wiki engine notes
Markdown (and thus Hugo) automatically concatenate pairs of lines, unless a newline or a double space is present at the end of the first line in the pair.
Templates can be invoked by {{< shortcode >}} or {{% shortcode %}}.
The correct usage can be found in comments in each shortcode’s file.
The Hextra theme’s shortcodes can be found here. This wiki’s shortcodes can be found here.
The version selector is generated by a shortcode, which reads list of versions from Hugo’s config.toml.
General styling notes
All styling described here must apply everywhere possible (e.g. Markdown does not allow a multi-sentence table field to be split across lines).
Page content should follow the xkcd 1285 formatting style, i.e. a new line after every sentence. These line breaks are ignored when content is rendered, but help reduce diff size and make the source more readable for documentation writers.
See this article and the Semantic Line Breaks specification for details that aren’t in comic panel form.
In addition:
- Code blocks should use 4 spaces, rather than tabs or some other indentation scheme.
- Warnings must go to the top of the section.
- All abbreviations must be capitalized.
- Spelling must follow standard United States English conventions.
- Trailing punctuation must be placed outside of any quotation marks.
When adding a new dispatcher, position arguments in a way, that answers the following questions:
- What is addressed?
- What action to perform?
- How to perfom the action?
HTML comments (<!-- -->) are not visible in the rendered page, but are useful for maintenance.
Use standard tags (WARNING: , NOTE: , TODO: , SORT: ) in the first line of the comment when appropriate.
Keep comment messages one space after the tag (TODO: body here).
Sorting config options
Tables of config options are sorted in the following manner:
Global toggle?
An enabled option, if it exists, must always be listed first.
Display or display-like?
If the table includes output, position, scale, transform, or rotation, these must be placed next, in the order they are listed here.
Other
Remaining options must be sorted alphabetically, with an exception (below) for cases where this would obscure meaning.
Special order
In some cases, multiple options act in a related manner, and would be more helpful if sorted together.
If any additional sorting was performed, add a comment (beginning with SORT: ) before the table to describe it.
Descriptions are free-form, they simply need to be understandable by others.
Also, mention the sorting in your PR.
Option descriptions
Descriptions must start with capital letter, and end without a period (full stop).
Keep descriptions concise. If additional explanation is needed, create a subsection below, and link to it from the table.
If an option only supports a particular set of predefined values, list them in the description. If there are more than four such predefined values, create a subsection and link to it from the table.
If an option has limits that are enforced by the config manager, specify them in the Limits field with respect to the type.