Content Styling
8 minute read.
This guide has many examples of how to style your documentation contributions. TrueNAS documentation uses standardized Commonmark Markdown, HTML, and Hugo syntax to transform text, add images, stylize tables, and link to other locations. The guide is not exhaustive but contains examples of the elements that are most commonly used when writing TrueNAS documentation. To learn more about each markup language, see these resources:
- Markdown: https://daringfireball.net/projects/markdown
- Commonmark: https://spec.commonmark.org/
- HTML: https://www.w3schools.com/html/default.asp
- Hugo: https://gohugo.io/documentation/
TrueNAS Documentation Hub articles make use of the following formatting options:
There are many style elements you can use that are built into the Hugo static site generator. This site uses Hugo shortcode syntax for images, internal references, and admonition boxes.
The documentation website also uses the Docsy theme. This theme has some additional styling elements that can be used to enhance your article. See the Docsy shortcodes guide for a list of built-in reusable content snippets.
Do not use the following in your articles:
The word will. It either does or does not do something. Use active voice and present tense when writing content. For example, do not type “The system will reboot.” Instead, use “The system reboots.”
The word may. We all say it but we are not giving permission to do something, we are saying it might do something. You can also replace may with can or should if these words better describe the situation. Only use may when granting permission to do something.
Do not use possessive case. Replace the (’s) instances with a statement. For example, do not say “The system’s IP address.” Instead, say “The IP address for the system.” You can use its or their, but try to avoid possessives where possible.
Do not use contractions. Contractions do not translate well for non-English and English as a second language reader populations. For example, change instances such as doesn’t to does not.
Spell out numbers between one and ten when referring to numbers of items in general terms. If you are referring to entering a number, type the digit (for example, enter 1 in the field). Use digits for numbers greater than ten.