Tutorial Content Creation Guide

  1. Install a browser spell checker!
    It deosn’t mettar how good yuor psot is technicaly, but if it cnotians speling and gramer erors all over the plais, yuor post will be itnreperted as low-kwaliti as the errors in italics on this line demonstrate. :stuck_out_tongue_winking_eye: :crazy_face:

  2. Ensure your post is readable
    This might seem like a no-brainer, but a “wall of text” is not readable, nor are inconsistent italics, Bold small and big font usage. :grin:

  3. Be consistent!
    It doesn’t matter whether you use:


    # Big


    ## Medium

    Extra bold

    ### Extra Bold
    headers to subdivide text, as long as you use the same system throughout your tutorial and please use different sizes for different (sub)sections…
    Even a simple Bold **Bold** like in this Guide is sometimes good enough. :+1:

  4. Use the [Details] section:
    If your post is longer than one screen,

    Click the triangle

    use the [details="Title"] [/details] markdown to hide text that is too long.

  5. Use correct indentation!
    Sometimes it’s just a matter of adding 2 spaces in front of a few lines (E.G. The details section above) to ensure the alignment is correct

E.G. This line is wrongly indented and it decreases the readability of the entire post! :sob:

  1. When writing a tutorial, the first line must contain a difficulty
    Copy-paste this: **Difficulty: ★☆☆☆☆** and assign it to a shortcut or whatever you use for automatic comments. Then cut the ★ and replace some of the ☆ with one or more ★ keeping 5 stars in total.

    Click the Triangle to have some more examples
    • Difficulty: ☆☆☆☆☆: Dead easy. I.E. Nothing to install, just run or type something
    • Difficulty: ★☆☆☆☆: Just one program to install from the standard repositories, simple tutorial
    • Difficulty: ★★☆☆☆: Just one program to install from the AUR or 2 from standard repositories, simple tutorial.
    • Difficulty: ★★★☆☆: Not for N00bs.
    • Difficulty: ★★★★☆: Definitely not for N00bs.
    • Difficulty: ★★★★★: you need to modify the kernel code yourself depending on non-obvious parameters and then recompile the kernel and install it yourself… :man_facepalming:
  2. Please use Manjaro commands (pamac, inxi) instead of Arch commands (pacman, lspci, …) wherever possible.

  3. Consistently use the <kbd> HTML directive for:

    • On-screen buttons like OK and Cancel
    • Keys on the keyboard like Ctrl+Alt+F2
    • Menu settings that have to be clicked like:
      • File, Print, Settings
      • System Settings, Screen, Compositor
  4. Re-read your post at least twice and edit out any errors you see.

  5. Optional: This is just a gripe of me personally and subjectively:
    Use long-format options when posting for N00bs, please!

    Click the triangle to read more on the optional requirement
    • Yes, I know that:
      inxy -Fazyxxx
      is the exact same as
      inxi --admin --verbosity=7 --filter --no-host --width
    • But the former is black voodoo to most N00bs whereas the latter one will tell them that you want:
      • admin parameters,

      • there is lots of information coming

      • Some stuff gets filtered

      • No host information will be given (In this case: host name)

      • Something with width (in this case: wrap lines when reaching end of terminal width)

        Why is this a gripe of me personally you ask?

        Well, In my past I’ve been a *nix admin where the *nix group decided to use the same operators as the Windows group so we could have a good night’s sleep instead of being called out of our beds all of the time.
        These operators used to make tons of mistakes as it’s easy to type 1 (one) letter wrong when following a process, but it’s hard to type an entire word wrong, so we standardized on long parameters for everyone .
        That is: for personal use, anyone could use anything they liked, but if you put a command in a script or in a process or a manual you had to use the long version!

        Result: Human Errors went down 90% and some scripts that sometimes misbehaved when Mars and Jupiter were in alignment suddenly had no issues any more! :first_quarter_moon_with_face: :earth_africa:


P.S. For more information on markdown, send a private message @discobot and type start advanced tutorial (or your local language version of that) or have a look over at CommonMark


Helpful post.

I have one comment for item number 6. I think UI items like menus should be distinguished from buttons. I don’t know if there is a markdown way of doing this.

I searched for an example and came up with asciidoctors user manual menu selection .

System Settings > Screen > Compositor

I just learned this today that a user can look at the raw post. It answers the question, “how’d they do that” :slight_smile: For example: https://forum.manjaro.org/raw/14112/1, where 14112 is the topic id and 1 is the post id. Would it be helpful to create a template that users could start with.

Item number 2, the “#” is semantically known as headers, similar to h1, h2, h3.

Commonmark has a short guide .


Thank you for your feed-back:

It’s just rule #6, so rule #2 Be consistent is much more important. If you don’t like button-shaped menu items: Don’t use them! But using buttons allows me to:

  • System SettingsScreenCompositor


  • System Settings
  • Screen
  • Compositor

depending on my needs


[Edit 1]: Title being replaced by Header right now! :man_facepalming: Thanks for that one too!
[Edit 2]: CommonMark added as a PS on top of the site-specific :robot: tutorial. :innocent:


I’m having a hard time with indentation in this post, doing the advanced discobot :partying_face: training atm after the commonmark 10 minute tutorial.

Using spaces to indent makes it a block quote

The post is not a wiki post yet, is that relevant?

Your tutorial looks good… What do you want to change??? (Also see PM = Personal Message I sent you after I edited that post)


You can use HTML / CSS:

<div style="margin-left: 10px">

       Look! I'm indented!



   Look! I'm indented!

Thanks for the tip, it works perfectly with normal text, alas not with the Summary option, unless I’m using it wrong?
Both of the way’s I presume it to have the indent effect:

<div style="margin-left: 10px">


This text should be indented



This text should be indented


<div style="margin-left: 10px">

This text should be indented



This text should be indented

Looking at the source it seems the function that does the flip decides that this block needs its own div and strips the extra supplied.

Like this:

<div style="margin-left: 10px">

       Look! I'm indented!



   Look! I'm indented!

:bulb: :thinking: I have been phrasing my question the wrong way
I was looking for a way to indent a normal paragraph this way without using a list and preserving the font.

Nah! That doesn’t work!

Markdown and HTML using discourse.org (the software our forum uses) is limited to whatever nokogumbo allows…


An em space can indent a single line of text:

  This text should be indented
    2 x Indented

&emsp; This text should be indented
&emsp; &emsp; 2 x Indented

A paragraph following a list item (bulleted or numbered) can inherit the list item indent:

  • Space

    Space is big. You just won’t believe how vastly, hugely, mind-bogglingly big it is. I mean, you may think it’s a long way down the road to the chemist’s, but that’s just peanuts to space
* Space</br>
Space is big. You just won't believe how vastly, hugely, mind-bogglingly big it is. I mean, you may think it's a long way down the road to the chemist's, but that's just peanuts to space

If a space after the list item is not needed, subsequent lines only need a single space for indentation:

  1. Time
    Time is an illusion
    Lunchtime doubly so
2. Time
 Time is an illusion
 Lunchtime doubly so

But I have not come across a way to indent a single paragraph

1 Like