Post formatting guide

Knowledge Base Mikrotik
1

Post editing and formatting in Discourse

Editing

In Discourse for creating/editing post you use system provided WYSIWYG editor that
formats text with Markdown syntax with some additions for extended functionality.
Like Poll and Table creation wizards and some other things. While it will provide
you with practically all that is required for comfortable use of system. But for
advanced editing knowing a bit more Markdown syntax details will be useful.

Notes on Editor

  • Editor provides live preview that can be activated by:
    • First button from the left side in editors toolbar.
    • Ctrl+M if in active editor.
    • >> button in editor lower right bottom.
  • When pasting Script, Configuration, Logs it is recommended that:
    • You use codebrackets to contain this text block for better viewing/reading of the content.
    • Selected syntax language for codebracket block, if applicable. As this can be ignored on basic text blocks.
    • Check for sensitive info before posting post or reply.

Formatting

Guide on how to use text formatting in discourse for better post composition. By default Discourse
uses Markdown formatting language with some additions for functionality. But for convenience of
our longer users we have enabled BBcode support via plugin.

Markdown

Notes on Markdown

  • Markdown syntax wants that you leave blank lines in-between various elements likes
    headings, lists, blockquotes, code brackets, horizontal rules, etc.
  • Indentations is somewhat important, at least in single sections for correct markdown rendering.

Headers

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

Emphasis

Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes ~~Scratch this.~~
Single line code uses single tilde `text`

Emphasis, aka italics, with asterisks or underscores.
Strong emphasis, aka bold, with asterisks or underscores.
Combined emphasis with asterisks and underscores.
Strikethrough uses two tildes. Scratch this.
Single line code uses single tilde text

Lists

1. First ordered list item
2. Another item
⋅⋅⋅⋅* Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
⋅⋅⋅⋅1. Ordered sub-list
4. And another item.

⋅⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above,
  and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

⋅⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅
⋅⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅
⋅⋅⋅⋅(This is contrary to the typical GFM line break behavior, where trailing spaces are not required.)

* Unordered list can use asterisks
- Or minuses
+ Or pluses

  1. First ordered list item

  2. Another item

    • Unordered sub-list.

  3. Actual numbers don't matter, just that it's a number

    1. Ordered sub-list

  4. And another item.

    You can have properly indented paragraphs within list items. Notice the blank
    line above, and the leading spaces (at least one, but we'll use three here to
    also align the raw Markdown).

    To have a line break without a paragraph, you will need to use two trailing spaces.
    Note that this line is separate, but within the same paragraph. (This is contrary
    to the typical GFM line break behavior, where trailing spaces are not required.)

  • Unordered list can use asterisks
  • Or minuses
  • Or pluses
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media
  • Write the press release
  • Update the website
  • Contact the media

Tables

  • Basic table

    | Syntax    | Description |
|-----------|-------------|
| Header    | Title       |
| Paragraph | Text        |
    Syntax Description
    Header Title
    Paragraph Text

  • Table with col alignments

    | Syntax    | Description |   Test Text |
|:----------|:-----------:|------------:|
| Header    |    Title    | Here's this |
| Paragraph |    Text     |    And more |
    Syntax Description Test Text
    Header Title Here's this
    Paragraph Text And more

Blockquotes

  • Simple blockquote

    > Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

    Dorothy followed her through many of the beautiful rooms in her castle.

    The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

  • Nested blockquotes

    > Dorothy followed her through many of the beautiful rooms in her castle.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

    Dorothy followed her through many of the beautiful rooms in her castle.

    The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

  • With various elements in blockquote

    > #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
>  *Everything* is going according to **plan**.

    The quarterly results look great!

    • Revenue was off the chart.
    • Profits were higher than ever.

    Everything is going according to plan.

Codeblocks

Discourse for codeblocks supports highlighting of various syntaxes using highlight.js implementation.

By default list of supported syntaxes: bash, c, cpp, css, csharp,css, diff, go,
graphql, ini, java, javascript, json, kotlin, lua, makefile, markdown, objectivec.
perl, php, php-template, plaintext, python, python-repl, r, ruby, rust, scss, shell,
sql, swift, typescript, xml, yaml, wasm

We added: routeros

  • RouterOS syntax

    ```routeros
:global funcA do={ :return 5 }
:global funcB do={
  :global funcA;
  :return ([$funcA] + 4)
}
:put [$funcB]
```

    :global funcA do={ :return 5 }
:global funcB do={  
  :global funcA;  
  :return ([$funcA] + 4)
}
:put [$funcB]

  • Python syntax

    ```py
text = input('Type a number, and its factorial will be printed: ')
n = int(text)

if n < 0:
    raise ValueError('You must enter a non-negative integer')

factorial = 1
for i in range(2, n + 1):
    factorial *= i

print(factorial)
```

    text = input('Type a number, and its factorial will be printed: ')
n = int(text)

if n < 0:
    raise ValueError('You must enter a non-negative integer')

factorial = 1
for i in range(2, n + 1):
    factorial *= i

print(factorial)

Horizontal Rules

***

---

___

All three will be rendered identically be markdown engines. Like the one below.

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the
document. When you create a footnote, a superscript number with a link appears where
you added the footnote reference. Readers can click the link to jump to the content
of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([1]).
Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers
only correlate the footnote reference with the footnote itself — in the output,
footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and
text ([1:1]: My footnote.). You don’t have to put footnotes at the end of the document.
You can put them anywhere except inside other elements like lists, block quotes, and tables.

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

  Indent paragraphs to include them in the footnote.
  `{ my code }`
  Add as many paragraphs as you like.

Here's a simple footnote,[1:2] and here's a longer one.[2]

Links

[mikrotik.com](https://mikrotik.com)
[some other article in discourse](/t/forum-rules-guide-lines/)
[some other article in discourse  - with specific post link](/t/how-to-format-your-posts-text/262158/27)

mikrotik.com
some other article in discourse
some other article in discourse - with specific post link

Images

![icon-winbox](https://data-discourse.cdn.mikrotik.com/App_Winbox.webp)
![icon-winbox](https://data-discourse.cdn.mikrotik.com/App_Winbox.webp "icon-winbox")
[![icon-winbox w/ description and link](https://data-discourse.cdn.mikrotik.com/App_Winbox.webp "icon-winbox")](https://mikrotik.com/download)

icon-winbox
icon-winbox
icon-winbox w/ description and link

URLs

To quickly turn a URL or email address into a link, enclose it in angle brackets.

<https://www.markdownguide.org>
<fake@example.com>

The rendered output looks like this:

https://www.markdownguide.org
fake@example.com

Escaping Characters

To display a literal character that would otherwise be used to format text in a
Markdown document, add a backslash () in front of the character.

\* Without the backslash, this would be a bullet in an unordered list.

The rendered output looks like this:

* Without the backslash, this would be a bullet in an unordered list.

Character Name
\ backslash
` backtick (see also escaping backticks in code)
* asterisk
_ underscore
{ } curly braces
brackets
< > angle brackets
( ) parentheses
# pound sign
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
| pipe (see also escaping pipe in tables)

BBcode (legacy BB syntax via plugin)

Primarily we encourage to use markdown as formatting syntax, but if required some
of BBcode syntax can also be used. In Discoure it's provided by official plugin.

Credits and Original articles

Article is based on markdown guide/samples in: www.markdownguide.org

If you think that there are some more examples that should be added or there are
some errors/mistakes, then please create topic with feedback in Site feedback
category with with your feedback/suggestions.

  1. This is the first footnote. ↩︎ ↩︎ ↩︎

  2. Here's one with multiple paragraphs and code.
    Indent paragraphs to include them in the footnote.
    { my code }
    Add as many paragraphs as you like. ↩︎

7 Likes