The editor in Discourse has a great deal of flexibility. Markdown is the standard method of entry. But it also allows certain BBCode tags and certain HTML tags. To find more details of the supported formatting and best practice recommendations, see the Discourse documentation.
But Markdown is so much more than just text. And that’s a key reason why it’s powerful for documentation.
Checkboxes
We use this in some of the category topic templates. Markdown allows you to create a checkbox in your content which - if you have edit permission - can even be checked when reading the article.
The syntax is simple. [ ] will be converted to an empty checkbox. If you want to make it pre-ticked, the syntax is [x]. Very cool!
Links
Links can be added by using the Hyperlink button in the editor’s actions row. Or you can just use standard Mardown syntax: [title](link). External links will automatically be opened in a new tab, this has been configured in the site settings. Alternatively, if you just paste a link it will be automatically replaced with the page title. This is specific to the Discourse editor.
Headings
Standard Markdown rules apply. # is a h1, ## is a h2, ### is a h3, #### is a h4. Markdownlint rules recommend a blank line around headings.
Numbering
You can just start numbering and it will automatically increment the numbers. But then you might later add another number in between. So Markdown syntax allows you to just use 1. each time and it will automatically increment.
If you want sub-numbering or bullets for a numbered item, you’ll need to indent. Do this by using spaces. In a browser, tab means move to the next field.
Code blocks
Standard markdown rules apply. Code blocks are done with fenced blocks. This means three backticks (```) on a separate line around your code, and a blank line either side.
You can also specify the language using standard highlightjs language codes. This include vss for VoltScript and lss for LotusScript.
You can also enable line numbering support for your code blocks. This is done by adding linenums=1 after the language, e.g.:
```java linenums=1
Mermaid Diagrams
Mermaid diagrams are also supported. As with other documentation frameworks, these are entered as code blocks with the language as mermaid. It’s recommended that you ensure your mermaid code is running on mermaid.live and indented with 4 spaces.
Note: The component currently uses Mermaid version 10.6.1. Mermaid is constantly evolving and adding support for new diagram types and syntax, so ensure the syntax you’re trying to use is supported in version 10.6.1.
BBCode plugin
Note, we do not intend at this time to add the BBCode plugin to extend the out-of-the-box supported tags.