Unity Discussions formatting reference

This post documents how to use the features of the post composer and Markdown used by Unity Discussions.

Use the table of contents in the top right of the post to navigate the sections.

This document is not exhaustive. Discourse is the platform behind Unity Discussions, which allows Markdown, BBCode, and some HTML. If you want to achieve something, research those topics and test to see if it works here.


Code blocks

Create a code block via the interface

  1. Paste your code into the composer.
  2. Select the code you just pasted.
  3. Select the Preformatted text button ➀, or press Ctrl E.
  4. Specify the language on the first line ➁ of the new code block to color code it.
    To specify C# use csharp or cs.

Create a code block manually

  1. Paste your code into the composer.
  2. Place three backticks ` or tildas ~ before and after your code.
  3. Specify the language on the first line of the code block to color code it.
    To specify C# use csharp or cs.
```csharp
// Your code here
```

Inline code

To format inline/single-line text as code, you can surround it with single backticks `:
`example` → example
Avoid using this for multi-line text, as it won’t format correctly.

Using the Preformatted text button—or pressing Ctrl E—on a single or partial line will also format as inline code.


Escaping formatting

To escape formatting you can use the backslash \ escape character:
\`example\` → `example`


User Quotes

  1. Highlight the post content you want to quote ➀.
  2. Select the Quote button ➁.
  3. The highlighted content is added to your post as a user quote.


Blockquotes

Creating a blockquote via the interface

  1. Write the content you want to quote in the post composer.
  2. Highlight the quote content ➀.
  3. Select the Blockquote button ➁ or press Ctrl Shift 9.
  4. The highlighted content will be formatted as a quote.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Creating a blockquote manually

Prefix every line you want to format as a blockquote with an angled bracket: >.

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
> 
> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.


Bulleted lists

Create a simple bulleted list via the interface

The interface does not support indents, multi-line, or paragraphs, you have to manually edit the results to introduce those features.

  1. Select the lines you want to turn into a bulleted list ➀.
  2. Select the Bulleted list button ➁ or press Ctrl Shift 8.

  • Example 1
  • Example 2
  • Example 3

Create a bulleted list manually

Simple bullet points

Add a hyphen - or asterisk * and a space before a line to make it a bullet point.

- Example 1
- Example 2
  • Example 1
  • Example 2

Indented bullet points

Add two spaces before a line to indent it once.

- Example 1
  - Example 1.1
- Example 2
  • Example 1
    • Example 1.1
  • Example 2

Multi-line and indented paragraphs

Multi-line

Indent text with two spaces for each indent level you want to attribute the paragraph to.

- Example 1
  Also Example 1
- Example 2
  • Example 1
    Also Example 1
  • Example 2
- Example 1
  - Example 1.1
    Also Example 1.1
- Example 2
  • Example 1
    • Example 1.1
      Also Example 1.1
  • Example 2

Multiple paragraphs

To add multiple paragraphs in a single bullet point, combine multi-line formatting with a line break tag <br>.

- Example 1<br>
  Also Example 1
- Example 2
  • Example 1

    Also Example 1
  • Example 2

Numbered lists

Create a simple numbered list via the interface

The interface does not support indents, multi-line, or paragraphs, you have to manually edit the results to introduce those features.

  1. Select the lines you want to turn into a numbered list ➀.
  2. Select the Numbered list button ➁ or press Ctrl Shift 7.

  1. Example 1
  2. Example 2
  3. Example 3

Create a numbered list manually

Simple numbered lists

Add 1, a period ., and a space, before a line to make it a numbered list.
You don’t need to count in the list, this will be done automatically. Save yourself the effort!

1. Example 1
1. Example 2
  1. Example 1
  2. Example 2

Indented bullet points

Add three spaces before a line to indent it once.

1. Example 1
  1. Example 1.1
1. Example 2
  1. Example 1
    1. Example 1.1
  2. Example 2

Multi-line and indented paragraphs

Multi-line

Indent text with three spaces for each indent level you want to attribute the paragraph to.

1. Example 1
   Also Example 1
1. Example 2
  1. Example 1
    Also Example 1
  2. Example 2
1. Example 1
   1. Example 1.1
      Also Example 1.1
1. Example 2
  1. Example 1
    1. Example 1.1
      Also Example 1.1
  2. Example 2

Multiple paragraphs

To add multiple paragraphs under a single number, combine multi-line formatting with a line break tag <br>.

1. Example 1<br>
   Also Example 1
1. Example 2
  1. Example 1

    Also Example 1
  2. Example 2

Task lists

Apply what you’ve learnt from bulleted and numbered lists and use it to create task lists.

- [x] Item marked as yes
- [ ] Item marked as no
  • Item marked as yes
  • Item marked as no

Foldouts

Creating simple foldouts via the interface

  1. Highlight the content you want to be hide in a foldout ➀ using the post composer.
  2. Select the Show more cog ➁.
  3. Select the Hide details button ➂.
  4. Alter the Summary text in the first line to describe what’s hidden.

[details="Summary"]
This text will be hidden
[/details]
Summary

This text will be hidden

Creating complex foldouts manually

You can use HTML markup to create foldouts, which allows for HTML styling inside the summary tag.

<details>
<summary>
<i>Spooky</i> text hidden within!
</summary>

**Boo!**
</details>
Spooky text hidden within!

Boo!


Tables

You can create tables by using the following formatting. You don’t need to align the rows or column characters, however each row or column should have an equal counts.

| Frame | Frame time | Movement | Added | Total |
|-------|------------|----------|-------|-------|
| 1     | 0.02ms     | 100      | 100   | 100   |
| 2     | 0.04ms     | 200      | 200   | 300   |
Frame Frame time Movement Added Total
1 0.02ms 100 100 100
2 0.04ms 200 200 300

Markdown tables can be finicky to author, so use a web-based Markdown table generator, or an IDE like JetBrains Rider to generate them.


Embedded content

Most third-party website content can be embedded into any topic; simply by sharing its URL in the body of the topic.

For example, YouTube, or Vimeo videos, or GitHub Gists, can be embedded simply by sharing their URLs.

While some of those embeds will render the video, or the content via IFrames, some will have Discourse’s default Onebox format (try to Facebook links from below).

Here are some valid URL formats:

# YouTube
https://www.youtube.com/watch?v=dQw4w9WgXcQ

https://youtu.be/dQw4w9WgXcQ?si=a57oKHPTIfhkIXin

https://www.youtube.com/embed/dQw4w9WgXcQ

# Vimeo
https://player.vimeo.com/video/877473729

https://www.vimeo.com/877473729

https://vimeo.com/877473729

# GitHub Gist
https://gist.github.com/gormus/233bb045f64dabdb464eddbbe86c149d

# X (formerly known as Twitter)
https://twitter.com/unity/status/1742992113330016306

https://x.com/unity/status/1742992113330016306

# Facebook
https://www.facebook.com/unity3d/videos/looking-to-learn-unity-this-year-weve-got-you-covered-our-free-unity-essentials-/374418448648794/

https://www.facebook.com/watch/?v=374418448648794

Rebake the embedded content

If for any reason, the embedded content looks outdated, or somehow not rendered correctly try rebuilding the HTML.

Right below the post you have the embedded content, find the wrench icon, and click on it to open contextual menu. From the opening menu, select Rebuild HTML.

This action will force Discussions to pull the latest content from the linked source, and update the embed markup.


Mermaid diagrams

You can embed Mermaid diagrams in your posts using the following steps:

  1. Author a Mermaid diagram using an app like mermaid.live.
  2. Copy your diagram markup.
  3. Create a mermaid block (choose one):
    • Use code block formatting to create a block with mermaid as the specified language.
    • Select the Show more cog ➀, and then select the Mermaid chart button ➁.
  4. Paste your diagram into the body of the code block ➂.

Example code block

```mermaid height=378,auto
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

Example output

%%{init: {'themeVariables': {'fontFamily': 'Inter, arial, sans-serif' }}}%%
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Mathematics

Inline mathematics

Surround a single-line MathJax-compatible statement in dollar signs $ to render mathematics inline.

The magnitude of a 2D vector is $\sqrt{x^2 + y^2}$.

The magnitude of a 2D vector is \sqrt{x^2 + y^2}.

Mathematics blocks

Surround a multi-line MathJax-compatible statement in two dollar signs $ to render a mathematics block.

$$
\sqrt{(-1)} \; 2^3 \; \sum \; \pi
$$
\sqrt{(-1)} \; 2^3 \; \sum \; \pi

Image comparison sliders

You can embed image comparisons in your posts using the following steps:

  1. Select the Image comparison slider button ➀ to add the necessary markup to your post.
  2. Choose a horizontal or vertical slider by swapping tag ➁ between data-direction-horizontal and data-direction-vertical.
  3. Paste or embed two images into the image comparison div, replacing the placeholder text ➂.
    • Do not remove the new line between the div and your images!

Example markup

<div data-image-comparison-slider data-direction-horizontal>

![Alt text 1](upload://wL2mvYrzsK3HtPuy3vuFIZns5PF.jpeg)
![Alt text 2](upload://pbGy4VlNB8QeGOj15gQqgT0Gwac.jpeg)

</div>

Example output



Miscellaneous formatting and tips

Keyboard shortcuts

<kbd>Ctrl E</kbd>Ctrl E

Abbreviations

<abbr title="Integrated Development Environment">IDE</abbr>IDE

Horizontal rule

Three hyphens (-) after a newline creates a horizontal rule.


---

Nested code blocks

As long as the outside code block contains more backticks than the inner they can be nested.

````markdown
```csharp
// Example
```
````

Comments

Both HTML and Markdown comments will not be replicated in the output.

<!---
your comment goes here
and here
-->

[//]: # (commented and hidden content)

Extra formatting tips

  • If Markdown isn’t being properly formatted, sometimes an extra newline is required before the text.
  • If you need to pad with whitespace but it’s automatically reduced, you can use a Figure Space . Don’t use this in scenarios where content may be copy and pasted, as non-standard whitespace can cause issues when overlooked.

Footnotes

Create footnotes by adding named (often numbered) markup pairs.

  1. Add a superscript link in your text using [^1] (replace 1 to increment the number).
  2. Add a linked footnote using [^1]: (replace 1 with the associated name).

Example markup

Note that needs clarification[^1]. A second note that needs extra clarification[^extra].

[^1]: Clarification regarding the note.
[^extra]: Extra clarification regarding the note.

Some other text.

Example output

Note that needs clarification[1]. A second note that needs extra clarification[2].


  1. Clarification regarding the note. ↩︎

  2. Extra clarification regarding the note. ↩︎

4 Likes