Discourse UIs and documentation are currently being reviewed and edited to align with these guidelines. We are working toward full alignment as quickly as possible.
When writing for Discourse, take note of the following guidelines for formatting text. These guidelines apply to text in all areas, notably documentation and the Discourse UI.
Capitalisation
When writing documentation or UI text, default to using sentence case (i.e. the first letter of the phrase is capitalised and nothing else).
Important reminders:
- Headings, titles, and category names use sentence case.
- Names of Discourse features are not capitalised, with only the following exceptions:
Do not use any other formatting for feature names, including no bold, italics, backticks, quotation marks, or anything else.
Capitalisation exceptions include:
- Acronyms must always be capitalised appropriately.
- Product and brand names must be capitalised according to their brand guidelines.
- Plugin and theme names must be capitalised appropriately.
- When referring to menu items, button labels, or form options, capitalise the first letter of the first word - e.g. “Click the New topic button to start writing.”
- If something is capitalised in the UI for a good reason, then use that same capitalisation when writing documentation about it.
- Category and URL slugs are always lower case.
When in doubt, use sentence case.
Periods
Do not use a period for the following:
- Tooltips, image captions, or other UI elements with only one sentence
- Button labels
- Menu items
- List items not including a verb
Do use a period for the following:
- Regular sentences
- Tooltips, image captions, or other UI elements with more than one sentence
- List items including a verb
- Image
alttext
Caveat for list items: If you are writing a list with mixed items (i.e. some require a period and some don’t) use periods for all of them.
Emphasis
To emphasise words, default to using italics. You may also use bold if you feel it fits the context.
Backticks
Use backticks (``) for inline code, example URLs, and setting names. Do not use them for any other purpose.
Code blocks
When including blocks of code, specify the coding language wherever possible by adding it immediately after the opening fence (the initial three backticks) - e.g. ```css.
Last edited by @hugh 2024-10-01T00:03:27Z
Last checked by @hugh 2024-10-01T00:03:33Z
Check document
Perform check on document:
