Formatting your text

subtopic

#1

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 topics document embedding content, hiding content etc…

Content

1. Markdown formatting

2. BBCode formatting

3. HTML formatting

4. Creating multi-level lists

5. Using emojis


1. Markdown formatting

1.1. Cheatsheet

Type Or … to Get
*Italic* _Italic_ Italic
**Bold** __Bold__ Bold
# Heading 1 Heading 1
=========

Heading 1

## Heading 2 Heading 2
---------

Heading 2

[Link](http://a.com) [Link][1]

[1]: http://b.org
Link
![Image](http://url/a.png) ![Image][1]

[1]: http://url/b.jpg
Markdown
> Blockquote  
Blockquote

* List
* List
* List

- List
- List
- List

  • List
  • List
  • List

1. One
2. Two
3. Three

1) One
2) Two
3) Three

  1. One
  2. Two
  3. Three
Horizontal Rule

---
Horizontal Rule

***
Horizontal Rule
`Inline code` with backticks   Inline code with backticks
```
# code block
print '3 backticks or'
print 'indent 4 spaces'
```
····# code block
····print '3 backticks or'
····print 'indent 4 spaces'
# code block
print '3 backticks or'
print 'indent 4 spaces'
[text-direction=rtl]
العَرَبِيَّة
[/text-direction]
  [text-direction=rtl]العَرَبِيَّة[/text-direction]

Source: Markdown Reference

1.2. Details

Markdown is our preferred way of formatting content. It is also used by the integrated editor when using its toolbar buttons.

  1. 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.

  2. 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.

  3. 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.

  4. 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](http://edgeryders.eu), it will show as [Edgeryders] (http://edgeryders.eu).

For full details, see the Markdown manual.

2. BBCode formatting

You can accomplish the same formats as with Markdown, and also have some advanced features:

2.1. Basic text formatting

strong
[b]strong[/b]

 

emphasis
[i]emphasis[/i]

 

underlined
[u]underlined[/u]

 

strikethrough
[s]strikethrough[/s]

 

http://edgeryders.eu
[url]http://edgeryders.eu[/url]

 

email@domain.com
[email]email@domain.com[/email]

2.2. Lists, Images, Code

[img]http://url.com/image.png[/img]

 

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

The BBCode [code]…[/code] tag is only an inline element – linebreaks in its content are ignored in the output.

2.3. Special features

hiding details / "spoiler alert"

it’s a sled

[details=hiding details / "spoiler alert"]it's a sled[/details]

 

[quote="community_wiki, post:1, topic:2"]
Something this user said.
[/quote]

 

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

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

For more detailed usage instructions for right-to-left text, please refer to Writing in Arabic and other right-to-left scripts (RTL).

3. HTML formatting

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:

  • bold: <b>…</b>
  • italics: <i>…</i>
  • striked through: <s>…</s>
  • headings: <h1>…</h1>, <h2>…</h2> etc.
  • horizontal rule: <hr/>
  • line break: <br/>
  • paragraph: <p>…</p>
  • quote: <blockquote>…</blockquote>
  • bullet list: <ul> <li>…</li> </ul>
  • numbered list: <ol> <li>…</li> </ol>

However, by convention we use Markdown formatting as default, so these HTML tags are only used in special cases (such as automatically imported content). Markdown has the advantage to produce more readable source and is also used by default in the Discourse editor.

The more useful part of HTML formatting are the additional features it provides, compared with Markdown. The main ones are:

  • table: <table><tr><td>…</td></tr></table>
  • smallprint: <small>…</small> (for example for image credits)
  • superscript: <sup>…</sup>
  • subscript: <sub>…</sub>
  • link anchors: <a name="…"></a> (works only for hyperlinks in the same post)

4. Creating multi-level lists

Working with nested list provides you clean and smooth management of content formatting

4.1. Using Markdown

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

As a result, the following code:

1. Item 1

    * Subitem 1
    * Subitem 2

        * Subsubitem 1

2. Item 2

will create this output:

  1. Item 1

    • Subitem 1

    • Subitem 2

      • Subsubitem 1
  2. 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:

  1. 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.

  2. 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 lines or paragraphs in a list item, where paragraphs can be normal text, quotations or perhaps other elements as well. There are two alternatives to make this happen.

The first alternative is “one linebreak”.

1. Item, first paragraph
Item, second paragraph

    1. Subitem, first paragraph
Subitem, second paragraph
Subitem, third paragraph

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

  1. Item, first paragraph
    Item, second paragraph
    1. Subitem, first paragraph
      Subitem, second paragraph
      Subitem, third paragraph

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

1. Item, first paragraph

    Item, second paragraph

    1. Subitem, first paragraph

        Subitem, second paragraph

        Subitem, third paragraph

It produces real paragraphs in all cases:

  1. Item, first paragraph

    Item, second paragraph

    1. Subitem, first paragraph

      Subitem, second paragraph

      Subitem, third paragraph

Adding different paragraph types. In both alternatives from above, you can exchange the second, third etc. paragraph selectively with a quote or code section, both in their Markdown and BBCcode notations. This also works with BBCode quote sections that consist of multiple paragraphs themselves, by applying the “one empty line and four spaces per list level” rule to each of them. Example:

1. Item

    * Subitem, first paragraph

        [quote]
        Subitem, second paragraph

        Subitem, third paragraph
        [/quote]

        Subitem, fourth paragraph

            Subitem, fifth paragraph

This creates the following output:

  1. Item

    • Subitem, first paragraph

      Subitem, fourth paragraph

        Subitem, fifth paragraph
      

Since Markdown code sections need four-space-indents by themselves already, you have to add these to the “four spaces per list level” indent when using the second alternative from above. So in total: eight space characters for the first list level, 12 for the second etc…

An exception here is that when using the first alternative (line breaks) 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, continue with the second alternative to create the new text paragraph.

In the “one empty line and four spaces per list level” alternative from above, you can even exchange the second, third etc. paragraph of a list item selectively with sub-list items. The following code:

1. Item

    Subitem, first paragraph

    * Subitem, second paragraph

    Subitem, third paragraph

will produce:

  1. Item

    Subitem, first paragraph

    • Subitem, second paragraph

    Subitem, third paragraph

4.3. Using BBCode

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

4.4. 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>Item 1
        <ul>
            <li>Subitem 1</li>
            <li>Subitem 2</li></ul></li>
    <li>Item 2</li>
</ol>

produces this output:

  1. Item 1
    • Subitem 1
    • Subitem 2
  2. Item 2

The implementation has some bugs: whitespace before a closing tag results in a large vertical space, and empty lines break the code so that the remaining BBCode will appear as source instead. It is best to use Markdown for nested lists currently.

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 :smile: 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 .


How to embed external content into a topic?
:green_book: Dynalist Manual
:green_book: Discourse User Manual for edgeryders.eu
Adding a table of contents
It's hard to format things in Discourse