Text formatting on help.univention.com

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 :tada: ).
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! :sunglasses:

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 :+1:

(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 :wink:)

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 :slight_smile:

Happy formatting! :balloon:

9 Likes
Mastodon