Formatting text content

community_wiki · August 21, 2017, 7:48am

This topic is a linked part of a larger work: “Discourse Website Manual for edgeryders.eu”

This documents text formatting for a website based on the Discourse forum software, such as our platform edgeryders.eu. This topic is limited to changing the appearance (such as bold and italic) and layout (such as lists and tables) of text. Other manual sections document embedding images, multimedia content etc…

Content

1. Markdown formatting

1.1. Introduction to Markdown
1.2. Common formatting
1.3. Additional features

2. BBCode formatting

2.1. Common formatting
2.2. Additional features

3. HTML formatting

3.1. Common formatting
3.2. Additional features
3.3. Unsupported features

4. Details about lists

4.1. Using Markdown: multi-level lists
4.2. Using Markdown: multiple paragraphs per item
4.3. Using Markdown: different text types per item
4.4. Using Markdown: multiple lists per item
4.5. Using BBCode
4.6. Using HTML
4.7. Foldable lists

5. Using emojis

1. Markdown formatting

1.1. Introduction to Markdown

Markdown is our preferred way of formatting content. It is also used by the integrated editor when using its toolbar buttons. Let’s walk through the basic options in detail:

Changing text to Bold: To change text to Bold, use double asterisk or double Underscore symbol to enclose the words expected to be bold. For example: **This is bold** will change the format to This is Bold. Likewise, __Bold__ will change the format to Bold.
Changing text to Italic: Enclosing text in single asterisks * or underscores _ will change the word to Italic. For example: *Italic* will change the text to Italic. Likewise, _Italic_ will change the text into Italic.
Headings: For headings of the content, the hash symbol needs to be added before the text heading. There can be multiple levels of headings in your content, depending on the number of has symbols used. Normally you would use ## Heading Level 2 for sections, and ### Heading Level 3 for sub-sections and so on.
Hyperlinks: You can attach or add the desirable link to a piece of text to create a hyperlink. To attach the link you can use the “chain icon” toolbar button in the editor, or also the following code to create your desired link. You can customize your link by changing the name in the first bracket [ ]. For example, to link to this website you can write [Edgeryders](https://edgeryders.eu/), it will show as Edgeryders.

For full details, see the Markdown Reference.

1.2. Common formatting

This section lists the basic text formatting options in Markdown – “basic” means, those that Markdown, BBCode and HTML have in common. As said in the introduction, we prefer Markdown.

Type …	… or type …	… and you Get
Italic	_Italic_	Italic
Bold	__Bold__	Bold
~~Strikethrough~~		~~Strikethrough~~
# Heading 1	Heading 1 =========	Heading 1
## Heading 2	Heading 2 ---------	Heading 2
[Link](http://a.com)	[Link][1] ⋮ [1]: http://b.org	Link
<http://raw.url>		http://raw.url
> Blockquote		Blockquote
* List * List * List	- List - List - List	List List List
1. One 2. Two 3. Three	1) One 2) Two 3) Three	One Two Three
Horizontal Rule ---	Horizontal Rule ***	Horizontal Rule
`Inline code` with backticks		`Inline code` with backticks
``` # code block print 'use 3 backticks or' print 'indent 4 spaces' ```	····# code block ····print 'use 3 backticks or' ····print 'indent 4 spaces'	`# code block print 'use 3 backticks or' print 'indent 4 spaces'`

Source and further information: Markdown Reference

For raw URLs, the <…> Markdown formatting prevents any Markdown postprocessing filers (incl. Markdown Linkify and Inline Onebox in Discourse) to mess with the URL. The URL will be linked, but not modified in any way.

For code blocks, we use the code fences style (“``` … ```”) by default and also configured Discourse to do so. The “four spaces indent” style does not support code highlighting and suffers from messy indentations due to various bugs and quirks (see section 4.3 for details).

1.3. Additional features

tables
images
semigraphics
code highlighting [TODO]

2. BBCode formatting

You can accomplish the same formats as with Markdown, and there are also some advanced features.

2.1. Common formatting

This section lists the basic text formatting options that have equivalents in Markdown. As said above, you should usually prefer Markdown.

Bold text.
```
[b]bold[/b]
```
Result: bold
Italic text.
```
[i]italic[/i]
```
Result: italic
Underlined text.
```
[u]underlined[/u]
```
Result: underlined
Strikethrough text.
```
[s]strikethrough[/s]
```
Result: strikethrough
URLs.
```
[url]http://edgeryders.eu[/url]
```
Result: http://edgeryders.eu
E-mail links.
```
[email]email@domain.com[/email]
```
Result: email@domain.com
Quote section. When copy&pasting a text from an e-mail or document, using this markup around it is much faster than adding > … to each line. That’s a valid reason not to use Markdown for this case.
```
[quote]
Something quoted from somewhere.
[/quote]
```
Result:

Something quoted from somewhere.

2.2. Additional features

Extended quote section (Discourse specific). This kind of code is automatically generated when selecting text in Discourse and clicking the Quote button that appears.
```
[quote="community_wiki, post:1, topic:2"]
Something this user said, with a link to it.
[/quote]
```
Result:

Something this user said, with a link to it.

Code section.

[code]
<?php 
echo 'Hello world'; 
?>
[/code]

Result:

  <?php 
  echo 'Hello world'; 
  ?>

Hidden details. For more information about this element, see “Hiding details and editorial comments”.
```
[details=hiding details / "spoiler alert"]it's a sled[/details]
```
Result:

hiding details / "spoiler alert"

it’s a sled
Right-to-left text. We added this to Discourse using a plugin. For more details about the right-to-left text tag, please refer to Writing in Arabic and other right-to-left scripts (RTL). The function is currently broken, as you can see in the non-working example below.
```
[text-direction=rtl]
العَرَبِيَّة
[/text-direction]
```
Result:

[text-direction=rtl]
العَرَبِيَّة
[/text-direction]

3. HTML formatting

Use Markdown by default. You can freely mix HTML formatting and Markdown / BBCode formatting in Discourse, so HTML tags are yet another way to create formatting for those features that Markdown / BBCode offers. However, Markdown has several advantage, so where both Markdown and HTML offer a desired feature, by convention we use Markdown:

Markdown leads to more readable source.
Markdown is also created by the buttons of the Discourse editor and thus the markup language that most users will default to anyway.
HTML source formatting has to make do without empty lines for vertical spacing due to the way switching between HTML and Markdown works in Discourse (see below). As a result, the HTML source is visually hard to navigate and read.

HTML equivalents of Markdown formatting can be used in special cases however, for example for automatically imported content.

Switching between HTML and inline Markdown. Character-level Markdown formatting works in most HTML tags without issues. Example:

<small>**Small but bold!**</small>

Result: Small but bold!

Switching between HTML and block-level Markdown. For this, you have to finish the HTML mode by creating an empty line. This is possible also without closing all HTML tags, allowing to place a Markdown formatted paragraph or table or image and then to continue with HTML, closing the open tages. Example:

<details open><summary>

*Want to know an open secret?*

</summary>

> Open secrets don't exist. Everything is either open or a secret.

</details>

Result:

Want to know an open secret?

Open secrets don’t exist. Everything is either open or a secret.

As can be seen from <summary>…</summary> in the example above, this mechanism is still a bit buggy as it can create extra line breaks. In addition, you can not use the HTML source indentation level for your Markdown paragraphs, as “four spaces” at the start of the line mean code block formatting in Markdown. Instead, start Markdown formatted paragraphs without leading whitespace. Obviously, this makes the mixed HTML / Markdown source code hard to read and rarely a good idea in practice.

3.1. Common formatting

This section lists the basic text formatting options that have equivalents in Markdown. As said above, you should usually prefer Markdown.

bold: <b>…</b>, <strong>…</strong>
italics: <i>…</i>, <em>…</em>
strikethrough: <s>…</s> and <strike>…</strike>
inline code: <code>…</code>
headings: <h1>…</h1>, <h2>…</h2> to <h6>…</h6>
horizontal rule: <hr/>
line break: <br/>
paragraph: <p>…</p>
quote: <blockquote>…</blockquote>
code blocks: <pre><code>…</code></pre>
bullet list: <ul> <li>…</li> </ul>
numbered list: <ol> <li>…</li> </ol>
table: <table><tr><td>…</td></tr></table> (for details, see Adding tables)

3.2. Additional features

The more useful part of HTML in Discourse are the following additional capabilities compared to Markdown formatting:

Smallprint. For example for image credits.
```
<small>small text</small>
```
Result: small text
Superscript.
```
<sup>superscript</sup>
```
Result: ^superscript
Subscript.
```
<sub>subscript</sub>
```
Result: _subscript
Abbreviations. This tag allows to define abbreviations, and the long form will be shown when hovering over the text.
```
The <abbr title="European Union">EU</abbr> has a horrible copyright law.
```
Result: The EU has a horrible copyright law.
Buttons. This HTML element can be used to symbolize individual keyboard keys and also user interface buttons. Very useful when writing help texts.
```
<kbd>k</kbd> <kbd>+ New Topic</kbd> <kbd>**Fat Button**</kbd>
```
Result: k + New Topic Fat Button
Hidden details. This is equivalent to the BBCode [details="…"]…[/details] tag supported in Discourse, but provides additional options: formatting of the summary text, opportunity to use it inside HTML tables, and the opportunity to use proper source code formatting. For details, see “Hiding details and editorial comments: 2. Paragraph with hidden details (using HTML)”.
```
<details>
    <summary>Summary Text</summary>
    Hidden Details Text
</details>
```
Result:

Summary Text
Hidden Details Text
Insertions and deletions. Use this to explicitly show changes you made or propose to a text. It has nothing to do with a post’s edit history feature.
```
"Hello <del>world</del> <ins>universe</ins>."
```
Result: “Hello ~~world~~ universe.”
Numbered lists with custom start numbering. You can set the starting number of a numbered list, for example to continue somebody else’s list in another post, or to break up your own list into multiple parts, with other content in between.
```
<ol start="7">
    <li>One item.</li>
    <li>Another item.</li>
</ol>
```
Result:
1. One item.
2. Another item.
Definition lists. To define terms, you can list them in a list like this:
```
<dl>
    <dt>Coffee</dt>
    <dd>A black liquid.</dd>
    <dt>Milk</dt>
    <dd>A white liquid.</dd>
</dl>
```
Result:

Coffee

A black liquid.

Milk

A white liquid.
Aside content. This is meant to logically mark content that is only tangentially related to the main text content, such as content that would be placed in callout boxes or sidebars. At present, it visually appears the same as normal content, but that can be easily adapted with CSS in the Discourse theme.
```
<aside>
    Hello world.
</aside>
```
Result:

Hello world.
Link anchors. For explanations, see our help sections “Adding link targets” and “Adding a table of contents”.
```
<h1 id="heading--…">…</h1>
⋮
<h6 id="heading--…">…</h6>

<a name="…"></a>
```
Non-breaking space. Useful to create horizontal space at the beginning of a paragraph similar to a hanging indent, and vertical space when placed on its own line.
```
Normal line.
&nbsp; Line with a hanging indent.
```
Result:
Normal line.
Line with a hanging indent.
HTML entities. Useful as memorizeable special characters. There is a long list.
Indentation for anything. Lists provide indentation in multiple levels, but outside of lists Markdown provides no way to indent any content (including standard text paragraphs over quotes, code, hidden details sections, images and tables). This is esp. annoying for images, which are always left-aligned due to this.

As a hack, <ul> … </ul> and <ol> … </ol> without their <li> elements can be used to indent any such content. By nesting these elements, indentation can be done on multiple levels.

This hack can also be used inside Markdown lists, but in the code you have to use leading whitespace on the lines with the opening and closing tags properly (see section 4.3. for details) in order to create the indentation relative to the current list item and not relative to the left border of the document. Because the latter case would imply finishing the Markdown list. If that’s a numbered Markdown list, the numbering is reset and would start again from “1”, which is not what you want.
```
<ul>

  ![test image|88x31](upload://q7MC9yJNpYqjfS68RId87oHKzUE.png)

</ul>
```
Result:
Code blocks without background formatting. As a side effect of using <pre>…</pre> without an additional <code>…</code> tag inside, you can create preformatted text in fixed-width font but without the usual gray background of code blocks:
```
<pre>Hello 
world!</pre>
```
Result:
```
Hello 
world!
```
Code blocks with manual text formatting. Markdown can do automatic code highlighting, but you cannot manually change the formatting of characters inside a code block, for example to highlight a section in bold. With HTML, you can:
```
<pre><code>Hello <b>world</b>!</code></pre>
```
Result:
```
Hello world!
```

3.3. Unsupported features

Not all HTML features can be used, as some tags and attributes will be removed by Discourse when generating the output HTML (they will still be available in the editor, though). This includes:

all attributes, with a few exceptions like <a name="…">, <h… id="heading--…">.
HTML imagemap elements <map><area> … </area></map>
HTML element <progress> to render a progress bar; though this can be added with a plugin
all other HTML elements not listed as working, though many could be added with simple custom Discourse plugins

4. Details about lists

The following sections explain the rather intimidating details of list formatting in Discourse: how multiple list levels, paragraphs and text types combine.

4.1. Using Markdown: multi-level lists

You can use numbered and unnumbered lists, and mix them together on multiple levels.

As a result, the following code:

1. List 1, Item 1

    * List 2, Item 1
    * List 2, Item 2

        * List 3, Item 1

2. List 1, Item 2

will create this output:

List 1, Item 1
- List 2, Item 1
- List 2, Item 2
  - List 3, Item 1
List 1, Item 2

To avoid seeing confusing behavior if you change these lists later to include multiple paragraphs per list item (see below), you should already adhere to the following formatting standards, already shown in the example above:

Four spaces per level. Use four spaces per list level for indentation. Technically, three or more spaces will work per list level as long as you keep it the same for all items of one list level, but four spaces are required to place a second paragraph below a parent list item (see below). So using four spaces to mean “one hierarchy level” everywhere makes the code most easy to understand.
Empty line between list levels. Separate list items of different list levels with an empty line, while list items on the same list levels can be separated by either an empty line or just a line break. (An empty line will create a larger gap in this case.) Without this, the “four spaces per level” method to create multiple paragraphs per list item will not work properly (see below).

4.2. Using Markdown: multiple paragraphs per item

This is a confusing case. It happens when you want to have multiple paragraphs in a single list item. These paragraphs can be of different types like quotation or code, but in this section we show the basic principle only, with pure text paragraphs.

There are two alternatives to make this happen:

The first alternative is “one linebreak”.

1. List 1, Item 1, paragraph 1
    List 1, Item 1, paragraph 2
    1. List 2, Item 1, paragraph 1
        List 2, Item 1, paragraph 2
        List 2, Item 1, paragraph 3

It produces just linebreaks when used with ordinary text (no gap between paragraphs), but paragraphs when used mixed with quotations.

List 1, Item 1, paragraph 1
List 1, Item 1, paragraph 2
1. List 2, Item 1, paragraph 1
  List 2, Item 1, paragraph 2
  List 2, Item 1, paragraph 3

The second alternative is “one empty line and four spaces per list level”.

1. List 1, Item 1, paragraph 1

    List 1, Item 1, paragraph 2

    1. List 2, Item 1, paragraph 1

        List 2, Item 1, paragraph 2

        List 2, Item 1, paragraph 3

It produces real paragraphs in all cases:

List 1, Item 1, paragraph 1

List 1, Item 1, paragraph 2
1. List 2, Item 1, paragraph 1
  
  List 2, Item 1, paragraph 2
  
  List 2, Item 1, paragraph 3

4.3. Using Markdown: different text types per item

This builds on the basic technique of having multiple paragraphs of text in one list item, but now allows the paragraphs to be of different types: normal text, quotes, code or tables. It works with both alternatives to create multiple paragraphs in a list item (“one linebreak” and “one empty line and four spaces per list level”).

You can selectively replace any text paragraph of a list item, including the first, with:

a quote section, either in the Markdown or BBCcode notation

If a BBCode quote section contains multiple paragraphs of text, the “one empty line and four spaces per list level” rule must be applied to each paragraph. See the example below.

An exception here is that when using the “one line break” technique and inserting a quote paragraph with >… Markdown formatting, there is no way to switch back to normal text inside that list item. Because this quote is valid up to an empty line. In this case, you have to continue with the “one empty line and four spaces per list level” technique to create the next non-quote paragraph.
a code section, either in the Markdown or BBCcode notation

When using Markdown, it is recommended to use the ```…``` “codefences” code syntax because it leads to uniform indentations: you can choose how many spaces to use per list level as long as you use the same number on each line and it’s at least two. By convention, we use four spaces per list level. Also, the codefences code syntax provides syntax highlighting.

On the other hand, the “four spaces” Markdown code syntax does not provide syntax highlighting, requires a different indentation for the same list level, and is affected by a quirk or Discourse bug that means you can not choose the number of spaces per list indentation level. Instead, the required number of spaces is hardcoded as “six more than required for the parent list item”, which means four spaces for the code styling and two for the list level, breaking our convention to use four for that.
a hidden details section

If the hidden details section contains multiple paragraphs of text, the “one empty line and four spaces per list level” rule must be applied to each paragraph. See the example below.
a table, using HTML notation or Markdown table notation

As an exception, this works only with the “one empty line and four spaces per list level” technique to create multiple paragraphs per list item.

When using HTML notation, the list level is determined by the leading whitespace in the line starting with <table>. Whitespace in all other lines is just code cosmetics, except that you also need the right amount of leading whitespace in the line with </table> or list items after the table would appear on the wrong list level (this seems to be a Discourse bug). You can also paste all of the HTML code in one line, which makes it more compact and you only have to adjust leading whitespace on that one line.
a HTML block element

For example, a HTML table as described just above. It works for any other block-level HTML element too, though, including HTML lists. The same rules for indentation apply: use four spaces per list level in the lines with the opening and closing tags.

Example with all of the above:

*   [quote]
    Item 1, paragraph 1

    Item 1, paragraph 2
    [/quote]

    Item 1, paragraph 3

    Item 1, paragraph 4

    [details=List 1, Item 1, paragraph 5 (and 6-7 inside)]
    Item 1, paragraph 6

    Item 1, paragraph 7
    [/details]

    ```
    Item 1, paragraph 8
    ```

    | Col A | Col B | Col C   |
    |-------|-------|---------|
    | A1    | B1    | C1      |
    | A2    | B2    | :smile: |

    <table>
      <tr>
        <th>Col A</th>
        <th>Col B</th>
        <th>Col C</th>
      </tr>
      <tr>
        <td>A1</td>
        <td>B1</td>
        <td>C1</td>
      </tr>
      <tr>
        <td>A2</td>
        <td>B2</td>
        <td>:smile:</td>
      </tr>
    </table>

* Item 2, paragraph 1

Result:

Item 1, paragraph 1

Item 1, paragraph 2

Item 1, paragraph 3

Item 1, paragraph 4

List 1, Item 1, paragraph 5 (and 6-7 inside)

Item 1, paragraph 6

Item 1, paragraph 7
```
Item 1, paragraph 8
```
Col A Col B Col C

A1 B1 C1

A2 B2

Col A Col B Col C

A1 B1 C1

A2 B2 :smile:
Item 2, paragraph 1

4.4. Using Markdown: multiple lists per item

This is the most weird case: it is possible to nest multiple independent lists inside one multi-paragraph list item. It requires you to use the “one empty line and four spaces per list level” technique to create multiple parapgraphs in one list item. Then, you can exchange the second, third etc. paragraph of a list item with a nested list item – so far just the normal way to create multi-level lists. But now, you can switch back to a plain-text paragraph on the previous list level, and if you choose, you can again switch to a list item, starting another independent nested list.

Example:

1. List 1, Item 1, paragraph 1

    List 1, Item 1, paragraph 2

    1. List 2, Item 1, paragraph 1
    2. List 2, Item 2, paragraph 1

    List 1, Item 1, paragraph 3

    1. List 3, Item 1, paragraph 1
    2. List 3, Item 2, paragraph 1

    List 1, Item 1, paragraph 4

2. List 1, Item 2, paragraph 1

Result:

List 1, Item 1, paragraph 1

List 1, Item 1, paragraph 2
1. List 2, Item 1, paragraph 1
2. List 2, Item 2, paragraph 1
List 1, Item 1, paragraph 3
1. List 3, Item 1, paragraph 1
2. List 3, Item 2, paragraph 1
List 1, Item 1, paragraph 4
List 1, Item 2, paragraph 1

The same works with unordered lists.

Example:

* List 1, Item 1, paragraph 1

    List 1, Item 1, paragraph 2

    * List 2, Item 1, paragraph 1
    * List 2, Item 2, paragraph 1

    List 1, Item 1, paragraph 3

    * List 3, Item 1, paragraph 1
    * List 3, Item 2, paragraph 1

    List 1, Item 1, paragraph 4

* List 1, Item 2, paragraph 1

Result:

List 1, Item 1, paragraph 1

List 1, Item 1, paragraph 2
- List 2, Item 1, paragraph 1
- List 2, Item 2, paragraph 1
List 1, Item 1, paragraph 3
- List 3, Item 1, paragraph 1
- List 3, Item 2, paragraph 1
List 1, Item 1, paragraph 4
List 1, Item 2, paragraph 1

And you can of course also mix ordered and unordered lists, multiple paragraphs in the nested lists, of different text types, and so on in many levels. Madness!

4.5. Using BBCode

Lists are no longer possible with BBCode in recent versions of Discourse.

4.6. Using HTML

Lists, including multi-level nested lists and lists with multiple paragraphs per element, can be created using standard HTML elements. The following code:

<ol>
    <li>List 1, Item 1
        <ul>
            <li>List 2, Item 1</li>
            <li>List 2, Item 2</li>
        </ul>
    </li>
    <li>List 1, Item 2</li>
</ol>

produces this output:

List 1, Item 1
- List 2, Item 1
- List 2, Item 2
List 1, Item 2

4.7. Foldable lists

With bullets

An interesting way to structure really complex lists is to allow folding and unfolding every list item, in multiple levels. This is just an application of the basic technique described above. We use  ▷  to mark non-foldable list items in such a way that they (almost) properly align with foldable list items.

Example:

*   [details="List 1, Item 1"]
    *   [details="List 2, Item 1"]
        * List 3, Item 1
        * List 3, Item 2
        [/details]
    * &nbsp;▷&nbsp; List 2, Item 2
    [/details]

*   [details="List 1, Item 2"]
    *   [details="List 4, Item 1"]
        * List 5, Item 1
        * List 5, Item 2
        [/details]
    * &nbsp;▷&nbsp; List 4, Item 2
    [/details]

Result:

List 1, Item 1
- List 2, Item 1
  - List 3, Item 1
  - List 3, Item 2
- ▷ List 2, Item 2
List 1, Item 2
- List 4, Item 1
  - List 5, Item 1
  - List 5, Item 2
- ▷ List 4, Item 2

Without bullets (CSS solution)

The typical list bullets of unordered lists are redundant, as the fold / unfold triangle can visually function as a bullet as well.

The cleanest / best way to achieve that is to adapt the Discourse theme CSS so that a details element inside another details element will be shown with an indentation. Also, text should start aligned with normal text paragraphs. Obviously, you can enable this solution only when you’re admin of a Discourse platform.

.cooked > ul > details {
    margin-left: 2.7em;
    
    details {
        margin-left: 2.7em;
    }
    summary {
        margin-left: -4em;
    }
}

Then, foldable lists can be simply written like this, nicely using one indentation level per list level:

<ul>
<details><summary>List 1, Item 1</summary>
    <details><summary>List 2, Item 1</summary>
        <div>List 3, Item 1</div>
        <div>List 3, Item 1</div>
    </details>
    <div>List 2, Item 2</div>
    <div>List 2, Item 3</div>
</details>
<div>List 1, Item 2</div>
</ul>

Result:

List 1, Item 1

List 2, Item 1

List 3, Item 1

List 2, Item 2

List 2, Item 3

List 1, Item 2

Caveats:

To align properly with normal paragraphs of text, the summary element needs to be moved left. So first we have to move all paragraphs of the list right, which is done easiest with a <ul>…</ul> tag in Discourse (as that is already provided and we don’t have a class attribute or similar to make something like that with CSS).
At the same time, the proposed (and here applied) CSS uses the single outer <ul> element at the first tag level in a post to detect when the nested formatting is expected, to not interfere with any other / normal usage of the details element. So, it won’t work without that outer <ul>, and it won’t work inside other lists and tables, only at the root level of a post.

Without bullets (ul indentation hack)

Here is a technique for foldable lists without bullets that works in any Discourse installation, without need for changes to the theme.

Example:

<details><summary>List 1, Item 1</summary>
    <ul>
    <details><summary>List 2, Item 1</summary>
        <ul>
        <li>List 3, Item 1</li>
        <li>List 3, Item 2</li>
        </ul>
    </details>
    &nbsp;▷&nbsp; List 2, Item 2
    </ul>
</details>
&nbsp;▷&nbsp; List 1, Item 2

Result:

List 1, Item 1

List 2, Item 1

List 3, Item 1
List 3, Item 2

▷ List 1, Item 2

Caveats:

Indentation is achieved with the <ul>…</ul> HTML element, without the elements for list items. Since this is a hack, you cannot assume that this will work with all future versions of Discourse.
The equivalent is also possible with the [details="…"]…[/details] BBCode tag. However, since four spaces of indentation outside of a Markdown list or HTML source context means “Markdown code block formatting” to Discourse, you cannot indent such a foldable list according to the list level. This makes it hard to edit, which is why we prefer the HTML version from above.
If you can change your Discourse theme, the cleanest solution is to use the technique “with bullets” and then to hide the bullets with CSS. You can let your CSS rule detect an <a name="…">…</a> tag around your foldable list, as that is one of the few tags where user-defined attributes are not filtered out by Discourse.

Without bullets (definition list technique)

Here is another technique for foldable lists without bullets that works in any Discourse installation, without need for changes to the theme.

Example:

<dl>
    <dt><details>
        <summary>List 1, Item 1</summary>
        <dd>
            <dl>
                <dt><details>
                    <summary>List 1, Item 1</summary>
                    <dd>
                        <ul>
                            <li>List 3, Item 1</li>
                            <li>List 3, Item 2</li>
                        </ul>
                    </dd>
                </details></dt>
                <dt>&nbsp;▷&nbsp; List 1, Item 2</dt>
            </dl>
        </dd>
    </details></dt>
    <dt>&nbsp;▷&nbsp; List 1, Item 2</dt>
</dl>

Result:

List 1, Item 1 List 1, Item 1 List 3, Item 1 List 3, Item 2 ▷ List 1, Item 2: List 1, Item 1

List 3, Item 1

List 3, Item 2

▷ List 1, Item 2
▷ List 1, Item 2

Caveats:

It’s a messy, hard to edit HTML source.
The tag structure is not standard compliant for a <dl> element, as we (have to) do it like this:
```
<dl>
    <dt>…
        <dd>…</dd>
    </dt>
</dl>
```
It seems to work, though

5. Using emojis

You can select desired emojis with the emoji icon in the Discourse text editor.

For fast and easy formatting, you can type the emoji’s name, with a colon : at the start and end.
This also allows a shorthand trick: you can just type colon : and the first letter(s) of the emoji name. The list of relevant emojis will then appear on the screen for selection.

For example: to place the emoji you can type :smile: or, for the shorthand trick, just type :s and select it.

For a one-page overview reference of all the available emojis, refer to the Emoji Cheat Sheet .

Formatting text content

Content

1. Markdown formatting

1.1. Introduction to Markdown

1.2. Common formatting

Heading 1

Heading 2

1.3. Additional features

2. BBCode formatting

2.1. Common formatting

2.2. Additional features

3. HTML formatting

3.1. Common formatting

3.2. Additional features

3.3. Unsupported features

4. Details about lists

4.1. Using Markdown: multi-level lists

4.2. Using Markdown: multiple paragraphs per item

4.3. Using Markdown: different text types per item

4.4. Using Markdown: multiple lists per item

4.5. Using BBCode

4.6. Using HTML

4.7. Foldable lists

With bullets

Without bullets (CSS solution)

Without bullets (ul indentation hack)

Without bullets (definition list technique)

5. Using emojis