Text formatting on help.univention.com

[Grandjean]

At help.univention.com we use Discourse as forum software. Discourse understands Markdown (preferred), BBCode and HTML as formatting options for text. Most options are accessible via a button in the editor:

So if you don’t know one of the formatting options, just use the buttons (and learn Markdown at the same time automatically ).
Most options are straight forward and somewhat self explanatory. But when it comes to formatting preformatted text (e.g. code or terminal snippets), there are different methods which are worth a closer look:

Inline code

Let’s say we have the following line:

Please execute univention-check-join-status on your UCS system.

“univention-check-join-status” is a command, so you want to emphasize this by making it look like a command. This can be achieved by using single backticks:

Please execute `univention-check-join-status` on your UCS system.

becomes:

Please execute univention-check-join-status on your UCS system.

Much better!

You can also just mark “univention-check-join-status” with your mouse and then hit the “Preformatted text” Button ().
You can also use a keyboard shortcut: CTRL+SHIFT+C

Code Blocks

But what if the whole line or several lines all need to be preformatted text?
The workflow with the button is the same: mark the text, then hit the button or CTRL+SHIFT+C - but the result is a bit different:

Consider this Python snippet:

import sys
from univention.appcenter.ucr import ucr_keys, ucr_instance
sys.path.append("/etc/univention/templates/modules")
import create_portal_entries
import re
[…]

To get it into preformatted mode, the button adds three backticks above the first line and three backticks under the last line:

```
import sys
from univention.appcenter.ucr import ucr_keys, ucr_instance
sys.path.append("/etc/univention/templates/modules")
import create_portal_entries
import re
ids = set()
for key in ucr_keys():
    match = re.match("ucs/web/overview/entries/(admin|service)/([^/]+)/.*", key)
    if match:
        ids.add(key)
changes = dict((id, (None, None)) for id in ids)
create_portal_entries.handler(ucr_instance(), changes)
```

And this is how it looks:

import sys
from univention.appcenter.ucr import ucr_keys, ucr_instance
sys.path.append("/etc/univention/templates/modules")
import create_portal_entries
import re
ids = set()
for key in ucr_keys():
    match = re.match("ucs/web/overview/entries/(admin|service)/([^/]+)/.*", key)
    if match:
        ids.add(key)
changes = dict((id, (None, None)) for id in ids)
create_portal_entries.handler(ucr_instance(), changes)

The whole block is preformatted and we even have syntax highlighting!

Regarding syntax highlighting: sometimes we explicitly don’t want syntax highlighting. For example something like this:

root@master:~# ucr search --brief --non-empty nameserver[1-3] dns/forwarder[1-3]
dns/forwarder1: 192.168.0.3
nameserver1: 10.200.30.91

The autohighlighting assumes that the #-sign starts a comment and therefore colors it in light grey. But actually it’s the bash prompt of the user root followed by a command. That command is quite important, so it should not be overlooked. In this case the first three backticks should be followed by “text” to disable syntax highlighting:

```text
root@master:~# ucr search --brief --non-empty nameserver[1-3] dns/forwarder[1-3]
dns/forwarder1: 192.168.0.3
nameserver1: 10.200.30.91
```

This way, we get:

root@master:~# ucr search --brief --non-empty nameserver[1-3] dns/forwarder[1-3]
dns/forwarder1: 192.168.0.3
nameserver1: 10.200.30.91

Again: much better

(Or you use a user that is not root - this is a good security practice in general and your bash prompt will be a $-sign and no #-sign )

Alternatives

Instead of using

```text
[...]
```

we can also explicitly force a certain language, for example:

```python
[...]
```

or

```php
[...]
```

More Alternatives

Instead of backticks, we can also use four spaces before every line:

    # a comment
    if [ $? -eq "0" ]; then
      echo "It works."
    fi

becomes:

# a comment
if [ $? -eq "0" ]; then
  echo "It works."
fi

Please note that the four spaces don’t have any syntax highlighting.

One last option: the BBCode [code][/code] works, too, with syntax highlighting:

[code]
# a comment
if [ $? -eq "0" ]; then
  echo "It works."
fi
[/code]

becomes:

# a comment
if [ $? -eq "0" ]; then
  echo "It works."
fi

Other formatting options that are nice to know

In the text above I used a keyboard button formatting. This should work in every modern browser and can be achieved by using the HTML tag <kbd>:

<kbd>CTRL</kbd>+<kbd>ALT</kbd>+<kbd>DEL</kbd>

becomes:

CTRL+ALT+DEL

The end

Do you have any remarks or recommendations? Feel free to comment

Happy formatting!