An Unofficial Discourse User Reference Guide

This is a “quick” how-to guide for using Discourse forum/community software. It contains a majority of the common features avialble to users/content editors, but may not have complete coverage of the featureset. If anyone sees anything to add or correct, feel free to comment. If you’d like to learn more about the Discourse Editor’s syntax take a look at the commonmark (a flavor of markdown) docs for more info.

Table of Contents

Most of the time you'd want to use the editor bar ![image|26x19](upload://1NHdXju8NWnlwraOXq9BbqA7LQ9.jpg) or hotkey crtl+k, but the basic format is `[link text](https://digikey.com)` which will give you an example link that looks like this: [link text](https://digikey.com)

Note - Easier Editing with Links
Having long URLs intermingled in your editor can sometimes make it a pain so you can also offset the links using the syntax in the example below. Note you must have a blank line above the reference and the reference id can be any number, text, or punctuation.

This paragraph is much easier to read in the [editor][1] because you can 
[include][dklink] the links below the paragraph text or at the bottom of the page.
 
[1]: https://github.com/digikey/digikey-kicad-library
[dklink]: https://digikey.com

This paragraph is much easier to read in the editor because you can include the links below the paragraph text or at the bottom of the page.

Images

Adding images is quite easy, if there's an image in your clipboard, just paste it in, the forum will automatically upload the image and fill in the appropriate syntax to make the image appear. If you are linking an image which is already on the web, use the following syntax. `![title text](/uploads/default/original/2X/f/f2efd3f9c7eeb0a6f1ec321baa7a8d715465e47a.jpg)` Result: ![title text](/uploads/default/original/2X/f/f2efd3f9c7eeb0a6f1ec321baa7a8d715465e47a.jpg) You can also upload images directly using the editor button ![image|25x21](upload://9qYE3aiDjbKPpg96o3Z5mvxOk7Y.png)

Image Sizing

If you would like to resize a large image to a smaller image use the following syntax.

![Original|200x200]https://media.digikey.com/Photos/LulzBot/MFG_KT-PR0051.jpg)
![Percent|200x200, 50%](upload://3sr8AVp3W68xVqCnfK79RQHMNyf.jpeg)
![By Pixels|64x64](upload://3sr8AVp3W68xVqCnfK79RQHMNyf.jpeg)

Original

Resized 50% By Pixels

Text Formatting

For bold, italics and strike-through use the editor buttons image or directly type the markdown:

**bold word** or __bold word__
*italicized word* or _italicized word_
_combo of **bold** and **italic**_
~~strike-through word~~

bold word or bold word
italicized word or italicized word
combo of bold and italic
strike-through word

Alternatively, there’s some BBCode sytnax that a person can use
[b]like this[/b] like this
[i]or this[/i] or this
[u]underline[/u] underline

Font color is not natively supported, but there is a BBCode plugin that will allow for changes in font color.
One can also have some choice to change fonts or colors using the LaTeX-based mathjax plugin covered in the mathjax section of this guide. $\color{red}{red text}$ \color{red}{red text}

Headings

# H1
## H2
### H3
#### H4
##### H5
###### H6

horizontal rule is 3+ asterisks
***

H1

H2

H3

H4

H5
H6

horizontal rule


Lists

You can use the editor buttons for orderedimage or unordered image lists.

1. First ordered list item
2. second list item
   * sub-lists are offset by three spaces      
1. Specific numbers 
1. don't matter they will auto increment
1. auto increment

* unordered lists 
* are also possible
  1. First ordered list item
  2. Explicit second list item
    • sub-lists are offset by three spaces
  3. Specific numbers
  4. don’t matter they will auto increment
  5. auto increment
  • unordered lists
  • are also possible

Code Formatting

Inline code formatting

Surround a section of code with backticks (`) inline code formatting.
Typing:
`var x = 10;`
Results in:
var x = 10;
This can also be done as var x = 10; inline.

Present entire line as code by prefixing four (4) spaces (an extra newline before this)
Typing:

     var this = “is a line”;
Results in :

var this = "is a line";

Multi-Line Blocks of Code

Surrounding code with three backticks ``` will allow for code to span multiple lines
Typing:
```
function foo(bar){
     return bar+1;
}
```
Results in:

function foo(bar){
    return bar+1;
}

Syntax Highlighting
The code block will try to automatically choose a style for code, but you can explicitly call out the desired formatting.
```javascript
function foo(bar){
     return bar+1;
}
```
Results in:

function foo(bar){
    return bar+1;
}

Tables

Tables are second class citizens in Discourse, some of the formatting features and niceties work and some don’t.

Protip - The easiest way to get a table into discourse is to start a table in an spreadsheet, then copy & paste that table into the editor window. Discourse natively handles the format change and makes creating a table much easier. Excel and Google Sheets work great using this method.

A markdown table in Discourse needs at least the first two lines to exist:

|Color|Weight|Height|
|-|-|-|
|red|12|160|
|green|4|100|
Color Weight Height
red 12 160
green 4 100

You can also use HTML for tables.

<table>
  <tr>
    <th>Color</th>
    <th>Weight</th>
    <th>Height</th>
  </tr>
  <tr>
    <td>red</td>
    <td>12</td>
    <td>160</td>
  </tr>
  <tr>
    <td>green</td>
    <td>4</td>
    <td>100</td>
  </tr>
</table>
Color Weight Height
red 12 160
green 4 100

Adding Newlines in the Markdown Table format in Discourse
If you find yourself with the need for multiple controlled lines in a table cell you can simply add a <br> into your table expression.

|Color|Weight|Heights|
|-|-|-|
|red|12|160<br>140|
|green|4|100<br>80<br>40|
Color Weight Heights
red 12 160
140
green 4 100
80
40

Blockquotes

Blockquotes can be found in the editor bar button image
Puting a greater than sign > in front of so a line will create blockquotes
Typing:
> this is some blockquoted text
> this is another line of blockquoted text

this is not blockquoted
> this is another one
Results in:

this is some blockquoted text
this is another line of blockquoted text

this is not blockquoted

this is another one

Table of Contents

This is not a native feature of Discourse, you can manually create a TOC by using HTML headings with the appropriate ID rather than the ## heading sytnax. Make sure your id is prefixed with heading--, this is necessary because of the Discourse’s javascript app based architecture. Here is a quick example:

- [link to first heading](#heading--first-header)
- [link to second heading](#heading--second-header)
- [link to third heading](#heading--third-header)
- [link to fourth heading](#heading--fourth-header)
<h3 id="heading--first-header">First One</h3>
some text
<h3 id="heading--second-header">Second One</h3>
more text
<h3 id="heading--third-header">Third One</h3>
even more text
<h3 id="heading--fourth-header">Fourth One</h3>
ok no more text

First One

some text

Second One

more text

Third One

even more text

Fourth One

ok no more text

Using LaTeX for Formatted Math

The is an official Discourse plugin that uses Mathjax to enable LaTeX based formatting. The LaTeX syntax is a beast on it’s own so I’ll only point out a few examples. Look at the quick reference guide on stack exchange for more information. The basic usage is to use $ \some inline latex expression $ or to express in multi-line surround the LaTeX with $$.

$$
H(z)&=\sum_{k=0}^{\infty}{(k+1)z^{-k}}\\
&=\frac{z^2}{(z-1)^{2}}
\end{align}
$$
\begin{align} H(z)&=\sum_{k=0}^{\infty}{(k+1)z^{-k}}\\ &=\frac{z^2}{(z-1)^{2}} \end{align}

There is \color{red}{color\ text} and a variety of symbols(\alpha \omega \gamma \beta \Omega \Gamma), fonts availble(\mathscr{HELLO WORLD}), and other ways to express things \Biggl(\biggl(\Bigl(\bigl((x)\bigr)\Bigr)\biggr)\Biggr)

Using HTML

Other

If you’d ever like to see how someone else created their post you can use the following URL format to view the raw markdown https://forum.example.com/raw/{topicid}/{postid} take a look at the current post as an example.

Aligning items

If you’re trying to align images or wrap text, there isn’t a really great tools for either of these things. It’s possible with custom plugins, but it’s not yet supported in native Discourse.

How to place images that are linked and sized into tables on the Tech Forum.

Putting images in tables has been a serious struggle for me. I have had several people ask me how to do it and was always at a loss. I am happy to say I have finally figured out how to pull it off and I would like to share this with you.

We are after a table like the one below. It is your standard table with four cells. Each one contains an image and that image is linked to a product page.

Nuts

Thread size Metal Plastic
M3 image image
M4 image image

How to do this

First we need an image. I am using the technique where the address is linked to a variable and stored at the bottom of the page. Each of the four images are actually all the same size. The size can be changed in line by increasing or decreasing the pixel count in this code.

![image|100x100][M3Metal]

If I change both the horizontal and vertical size from 100 to 50, this is what happens:

Nuts

Thread size Metal Plastic
M3 image image
M4 image image

Next, I am going to link them to a Digi-Key product page using the same technique.

 ![image|100x100][M3Metal]
[                         ][M3MetalLink]
[![image|100x100][M3Metal]][M3MetalLink]

The line built above will work anywhere in your post, but if you try to put it in a table you will see it does not work as you intend. This code:

## Nuts 
|ThreadSize|Metal|Plastic|
|---|---|---|
|M3|[![image|100x100][M3Metal]][M3MetalLink] |[![image|100x100][M3Plastic]][M3PlasticLink] |
|M4|[![image|100x100][M4Metal]][M4MetalLink] |[![image|100x100][M4Plastic]][M4PlasticLink] |

[M3Metal]:upload://8jI37HvTmgnJrXP8itwyFCDGosD.jpeg
[M3MetalLink]:https://www.digikey.com/en/products/detail/b-f-fastener-supply/MHNZ-003/274973

[M3Plastic]:upload://izLuK5lgqjpuu1wjbTzQWLnEFUL.jpeg
[M3PlasticLink]:https://www.digikey.com/en/products/detail/essentra-components/HN-M3-79/391781

[M4Metal]:upload://MIDIwIPJGrnULIKMevZZImQlU9.jpeg
[M4MetalLink]:https://www.digikey.com/en/products/detail/b-f-fastener-supply/MHNZ-004/274974

[M4Plastic]:upload://izLuK5lgqjpuu1wjbTzQWLnEFUL.jpeg
[M4PlasticLink]:https://www.digikey.com/en/products/detail/essentra-components/HN-M4-79/391783


Will produce these results:

Nuts

ThreadSize Metal Plastic
M3 [![image 100x100]M3Metal]M3MetalLink
M4 [![image 100x100]M4Metal]M4MetalLink

Notice that the images do not show up? All we have is text? Also notice the space " " where the pipe " | " used to be in the code? It is treating the pipe differently than we intended in this situation.

The solution is to escape the pipe characters so they can work correctly. We do this by placing the character " \ " before the pipe

            \                                          \
|M3|[![image |100x100][M3Metal]][M3MetalLink] |[![image |100x100][M3Plastic]][M3PlasticLink] |

The correct code should look like this

|M3|[![image\|100x100][M3Metal]][M3MetalLink]|[![image\|100x100][M3Plastic]][M3PlasticLink]|

Thats all there is too it.

Here is the complete and correct code:

## Nuts
|Thread size|Metal|Plastic|
|:---:|:---:|:---:|
|M3|[![image\|50x50][M3Metal]][M3MetalLink]|[![image\|50x50][M3Plastic]][M3PlasticLink]|
|M4|[![image\|50x50][M4Metal]][M4MetalLink]|[![image\|50x50][M4Plastic]][M4PlasticLink]|

[M3Metal]:upload://8jI37HvTmgnJrXP8itwyFCDGosD.jpeg
[M3MetalLink]:https://www.digikey.com/en/products/detail/b-f-fastener-supply/MHNZ-003/274973

[M3Plastic]:upload://izLuK5lgqjpuu1wjbTzQWLnEFUL.jpeg
[M3PlasticLink]:https://www.digikey.com/en/products/detail/essentra-components/HN-M3-79/391781

[M4Metal]:upload://MIDIwIPJGrnULIKMevZZImQlU9.jpeg
[M4MetalLink]:https://www.digikey.com/en/products/detail/b-f-fastener-supply/MHNZ-004/274974

[M4Plastic]:upload://izLuK5lgqjpuu1wjbTzQWLnEFUL.jpeg
[M4PlasticLink]:https://www.digikey.com/en/products/detail/essentra-components/HN-M4-79/391783

Here is the table with the images linked.

Nuts

Thread size Metal Plastic
M3 image image
M4 image image

I hope this helps someone!

2 Likes

A different way of linking to other parts of your post

Enter this when writing your post.

[Table of contents Link One](#LinkOne)
[Table of contents Link Two](#LinkTwo)
[Table of contents Link Three](#LinkThree)
[Table of contents Link Four](#LinkFour)
[Table of contents Link Five](#LinkFive)
[Table of contents Link Six](#LinkSix)
[Table of contents Link Seven](#LinkSeven)
[Table of contents Link Eight](#LinkEight)
[Table of contents Link Nine](#LinkNine)


<a name="LinkOne">The Text of Link One </a>
<a name="LinkTwo">The Text of Link Two</a>
<a name="LinkThree">The Text of Link Three</a>
<a name="LinkFour">The Text of Link Four</a>
<a name="LinkFive">The Text of Link Five</a>
<a name="LinkSix">The Text of Link Six</a>
<a name="LinkSeven">The Text of Link Seven</a>
<a name="LinkEight">The Text of Link Eight</a>
<a name="LinkNine">The Text of Link Nine</a>

Then you will see this as a result

Table of contents Link One
Table of contents Link Two
Table of contents Link Three
Table of contents Link Four
Table of contents Link Five
Table of contents Link Six
Table of contents Link Seven
Table of contents Link Eight
Table of contents Link Nine
 
 
 
 
 
 
 
 
 
 

The Text of Link One
 
 
 
 
 
 
 
 
 
 
The Text of Link Two
 
 
 
 
 
 
 
 
 
 
The Text of Link Three
 
 
 
 
 
 
 
 
 
 
The Text of Link Four
 
 
 
 
 
 
 
 
 
 
The Text of Link Five
 
 
 
 
 
 
 
 
 
 
The Text of Link Six
 
 
 
 
 
 
 
 
 
 
The Text of Link Seven
 
 
 
 
 
 
 
 
 
 
The Text of Link Eight
 
 
 
 
 
 
 
 
 
 
The Text of Link Nine