Using Discourse

A short introduction to using a forum and collaboration site like Discourse in 2020.


Discourse is a modern forum built for better discussions and interactions.
It provides many features to help facilitate easier communication and to foster better discussions.

Formatting Posts

The primary interface for writing posts on the site use the Post Editor that looks like this:

Where the green box is the Title of the post.
Yellow is the post Category and optionally any tags.

Posts can be formatted using the formatting options (in orange).
In order, from left to right, they are:

  • Quote
  • Bold
  • Italic
  • Hyperlink
  • Blockquote
  • Pre-formatted text
  • Upload a file or image
  • Bulleted List
  • Numbered List
  • Emoji
  • Insert date/time
  • Options

Don’t let all of these options overwhelm you. Usually you’ll likely only use a few common ones like Bold, Italic, Hyperlink, Image upload.

Posts written in Discourse use CommonMark*, a lightweight markup language often used on the web.
* itself an extension of the original Markdown by John Gruber and Aaron Swartz

There are only a small handful of markup to format your posts with the most common formatting options. When in doubt, refer to the CommonMark reference:

For example:


You can divide your post with logical headings by using the hash # at the beginning of a line. The number of hashes defines the heading level:

# Heading one
## Heading two
### Heading three


To emphasis text with italics you can surround it with one of either underscore _ or asterisk *:

This is _italic_ and so is *this*.

This is italic and so is this.

To make it bold use two underscores __ or two asterisks **:

This is __bold__ and so is **this**.

This is bold and so is this.


You can insert a hyperlink by simply pasting a valid URL:

Discourse will turn it into a valid link automatically for you.

If you want different text to be a hyperlink:

[This is a link](

This is a link


If you want to include an image in your post, simply drag-and-drop the image file onto the Post Editor.

If you know the URL for the image, you can also use the CommonMark syntax:

![Alt Text](upload://1wMDtD9rxDYG2Kd3u9UkVjiL8E3.png)

Which will give you:

Alt Text


Lists can be created using either an asterisk * at the start of a line, or a number followed by a period:

* unordered
* list
* items
  • unordered
  • list
  • items


1. first
1. second
1. third
  1. first
  2. second
  3. third

(Note the number doesn’t need to be sequential, the numbering is handled for you.)

Mentioning Users (@-mentions)

If you want to get the attention of, or refer to, another user on the forum you can use @ followed by their username (Discourse will provide suggestions based on what you type):


This will trigger a notification to the user that they were mentioned.

Onebox Links

Some sites provide extra metadata when queried as a link that Discourse can pickup and embed directly in your post. For example, when providing a link to a YouTube video the entire video will become embedded in your post automatically:


this also works for internal links within Discourse:

Mailing List Mode

If you prefer to continue interacting through a mailing list and the site settings permit it, you can enable Mailing list mode in your account preferences. You’ll receive emails for posts and can email responses that will show up in the topic.