I created the this guide hoping it will lead to less clutter in various support threads.
This is a wiki-post, so you can click “Edit” to see how I created this post with Markdown and HTML.
Also, feel free to submit changes if you have further pointers you deem important.
Formatting Guide | Forum Editor
This forum uses Discourse - a very popular forum service. Its editor provides a special flavor of Markdown. For more details on Markdown, visit the official syntax guide by John Gruber. For specific information about Discourse, it’s best to check the GitHub repository.
Table of contents
- Basic formatting
1.1. Headings
1.2. Horizontal rule
1.3. Font styles
1.4. Lists
1.5. Tables - Code formatting
2.1. Inline code
2.2. Single line of code
2.3. Code block with syntax highlighting - Images
3.1. Resizing images - Social features
4.1. Quotes
4.2. Mentions
4.3. Hyperlinks - Advanced features
5.1. Hide details
5.2. Polls - Miscellaneous
6.1. Fancy keyboard shortcuts
6.2. Embed third party sites
1. Basic formatting
1.1. Headings
Proper use of headings can improve the readability of your posts. To create a heading, prepend a line with a specific number of #.
Available headings:
1.2. Horizontal rule
Horizontal rules are another good way to segment your content.
Syntax: --- (three hyphens)
The hyphens translate into an
<hr>. If there is no extra line between the content above and the hyphens, an underlined heading will be created.
1.3. Font styles
Bold text 
| Shortcut | Markdown | Output |
|---|---|---|
| Ctrl+B | **bold** | bold |
Italic text 
| Shortcut | Markdown | Output |
|---|---|---|
| Ctrl+I | *italic* | italic |
Strikethrough text
| Shortcut | Markdown | Output |
|---|---|---|
| ~~strike~~ |
1.4. Lists
Unordered list
Indent list items with 2 spaces to nest them:
| Editor input | Alternative | Output |
|---|---|---|
| - Item 1 - Item 2 - Item 3 |
* Item 1 * Item 2 * Item 3 |
|
Ordered list
Markdown automatically indents sub-items of an ordered list:
| Editor input | Output |
|---|---|
| 1. Item 1.1. Item 2. Item |
1. Item 1.1. Item 2. Item |
1.5. Tables
To create a table with Markdown, use the following syntax:
| Markdown | HTML | Image |
|:---------------|:-----------:|----------------:|
| justified left | centered | justified right |
| *italic* | <b>bold</b> |  |
The colons - e.g.
|:--|tell Markdown how to align the the cells’ content. You can even use Markdown or HTML within the cells and you can create multiline content with<br>tags.
Output
| Markdown | HTML | Image |
|---|---|---|
| justified left | centered | justified right |
| italic | bold |  |
2. Code formatting 
Discourse offers syntax highlighting for code snippets (HTML, CSS, JavaScript etc.).
- Shortcut: Ctrl+E
- Editor toolbar button:
<script>
console.log("Hello, world!");
</script>
While the shortcut is usually the fastest way, there are three options to do this manually, too:
2.1. Inline code
You can emphasise HTML tags, classes, functions or other technical jargon with inline preformatted text.
Syntax: wrap with single backtick (`)
- Shortcut: Ctrl+E
| Editor input | | Output |
|—|—|—|—|
| This `<hr>` is inline. | | This <hr> is inline. |
2.2. Single line of code
You can quickly create a single code line by indenting it with spaces (no syntax highlighting).
This line is indented with 4 spaces.
2.3. Code block with syntax highlighting
Code blocks are the best way to display template samples or error messages, since the code container offers syntax highlighting and the original format is respected.
Syntax: wrap with three backticks (```)
- Shortcut: Ctrl+E
Discourse uses highlight.js for syntax highlighting. When using a code block, it will try to automatically apply the correct syntax highlighting for the selected text.
Editor input
```
<script>
⠀⠀console.log(“This snippet has syntax highlighting.”);
</script>
```
Output
<script>
console.log("This snippet has syntax highlighting.");
</script>
Set desired language explicitly
You can also set the desired syntax explicitly.
This code block is explicitly set to JavaScript syntax highlighting:
``` javascript
function foo(bar) {
⠀⠀return bar + 1;
}
```
Output:
function foo(bar) {
return bar + 1;
}
The following code block will be interpreted as plain text:
``` text
function foo(bar) {
⠀⠀return bar + 1;
}
```
Output:
function foo(bar) {
return bar + 1;
}
3. Images 
You don’t need to upload your images to an external image hosting site!
You can easily add images to your posts per drag and drop or Ctrl+V from your clipboard. You can also use the button. Discourse will automatically apply the correct Markdown syntax.
3.1. Resizing images
You can resize uploaded images by adding special parameters:
| Original upload | Percentage | Pixels |
|---|---|---|
|  |  |  |
The editor also suggests the following sizes on hover:
4. Social features
4.1. Quotes
When highlighting content from another post, the following tooltip appears:
On click, Discourse will automatically create a quote in your editor at the current caret position.
The user you quoted will be notified when you publish the post, as it is handled like an answer.
4.2. Mentions
The correct way to adress someone directly in the forum is @username. This way that user will be notified and is therefore more likely to read your post.
4.3. Hyperlinks 
Hyperlinks serve a variety of functions. Proper linking helps make the forum a better knowledge base.
Shortcut: Ctrl+K
Syntax: [text](url)
Instead of quoting a post’s content, you can use it’s unique url to embed it into your post:
Websites that provide an oEmbed format (e.g. GitHub, YouTube, CodePen) can also be embedded this way (see 6.2.).
5. Advanced features 
5.1. Hide details 
If a section of your post is very specific (e.g. note template code) and won’t be of interest to a broader audience, you can use details to collapse that part:
Output:
Code
Very specific code that takes up a lot of space:
console.log("Hello, world!");
This is a very useful to keep your posts concise and tidy. It reduces visual clutter and makes scrolling through the thread easier.
5.2. Polls 
To prevent redundant posts like “+1” or “I agree” when asking for community feedback, you can create a poll.
Sample poll
- Yes
- No
6. Miscellaneous
6.1. Fancy keyboard shortcuts
You can wrap keyboard shortcuts with the
<kbd>HTML tag to display them more professionally:
| Editor input | Output |
|---|---|
<kbd>Ctrl<\kbd>+<kbd>A</kbd> |
Ctrl+A |
6.2. Embed third party sites
To embed YouTube videos, GitHub PRs or CodePens, simply paste the link into a new line in the editor. The embedded may be displayed as a gray box until the post is published.
YouTube
