Documentation cheat sheet

The documentation files use a mixture of Markdown and MyST syntax.

See the following sections for syntax help and conventions.

Headings

Input

Description

# Title

Page title and H1 heading

## Heading

H2 heading

### Heading

H3 heading

#### Heading

H4 heading

…

Further headings

Adhere to the following conventions:

  • Do not use consecutive headings without intervening text.

  • Use sentence style for headings (capitalize only the first word).

  • Do not skip levels (for example, always follow an H2 with an H3, not an H4).

Inline formatting

Input

Output

*Italic*

Italic

**Bold**

Bold

`code`

code

Adhere to the following conventions:

  • Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept).

  • Use bold sparingly. A common use for bold is UI elements (“Click OK”). Avoid using bold for emphasis and rather rewrite the sentence to get your point across.

Code blocks

Start and end a code block with three back ticks:

```

You can specify the code language after the back ticks to enforce a specific lexer, but in many cases, the default lexer works just fine.

Input

Output

 

```
# Demonstrate a code block
code:
- example: true
```


# Demonstrate a code block
code:
- example: true


```yaml
# Demonstrate a code block
code:
- example: true
```


# Demonstrate a code block
code:
- example: true

To include back ticks in a code block, increase the number of surrounding back ticks:

Input

Output

 

````
```
````



```

Lists

Input

Output

 
- Item 1
- Item 2
- Item 3

  • Item 1

  • Item 2

  • Item 3

 
1. Step 1
1. Step 2
1. Step 3

  1. Step 1

  2. Step 2

  3. Step 3

 
1. Step 1
   - Item 1
     * Subitem
   - Item 2
1. Step 2
   1. Substep 1
   1. Substep 2

  1. Step 1

    • Item 1

      • Subitem

    • Item 2

  2. Step 2

    1. Substep 1

    2. Substep 2

Adhere to the following conventions:

  • In numbered lists, use 1. for all items to generate the step numbers automatically.

  • Use - for unordered lists. When using nested lists, you can use * for the nested level.

Definition lists

Input

Output

 
Term 1
: Definition

Term 2
: Definition
Term 1

Definition

Term 2

Definition

Tables

You can use standard Markdown tables. However, using the rST list table syntax is usually much easier.

Both markups result in the following output:

Header 1

Header 2

Cell 1

Second paragraph cell 1

Cell 2

Cell 3

Cell 4

Markdown tables

| Header 1                           | Header 2 |
|------------------------------------|----------|
| Cell 1<br><br>2nd paragraph cell 1 | Cell 2   |
| Cell 3                             | Cell 4   |

List tables

```{list-table}
   :header-rows: 1

* - Header 1
  - Header 2
* - Cell 1

    2nd paragraph cell 1
  - Cell 2
* - Cell 3
  - Cell 4
```

Notes

Input

Output

 
```{note}
A note.
```

Note

A note.

 
```{tip}
A tip.
```

Tip

A tip.

 
```{important}
Important information
```

Important

Important information.

 
```{caution}
This might damage your hardware!
```

Caution

This might damage your hardware!

Adhere to the following conventions:

  • Use notes sparingly.

  • Only use the following note types: note, tip, important, caution

  • Only use a caution if there is a clear hazard of hardware damage or data loss.

Images

Input

Output

 
![Alt text](https://linuxcontainers.org/static/img/containers.png)

Alt text

 
```{figure} https://linuxcontainers.org/static/img/containers.png
   :width: 100px
   :alt: Alt text

   Figure caption
```
Alt text

Figure caption

Adhere to the following conventions:

  • For pictures in the doc folder, start the path with / (for example, /images/image.png).

  • Use PNG format for screenshots and SVG format for graphics.

Reuse

A big advantage of MyST in comparison to plain Markdown is that it allows to reuse content.

Substitution

To reuse sentences or paragraphs without too much markup and special formatting, use substitutions.

Substitutions can be defined in the following locations:

  • In the substitutions.yaml file. Substitutions defined in this file are available in all documentation pages.

  • At the top of a single file in the following format:

    ---
myst:
  substitutions:
    reuse_key: "This is **included** text."
    advanced_reuse_key: "This is a substitution that includes a code block:
                       ```
                       code block
                       ```"

---

You can combine both options by defining a default substitution in reuse/substitutions.py and overriding it at the top of a file.

Input

Output

{{reuse_key}}

This is included text.

{{advanced_reuse_key}}

This is a substitution that includes a code block: code block

Adhere to the following convention:

  • Substitutions do not work on GitHub. Therefore, use key names that indicate the included text (for example, note_not_supported instead of reuse_note).

File inclusion

To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations.

You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file.

By combining file inclusion and substitutions, you can even replace parts of the included text.

Input

Output

 

% Include parts of the content from file [../README.md](../README.md)
```{include} ../README.md
   :start-after: Installing from source
   :end-before: Second, download the source code
```

To compile distrobuilder from source, first install the Go programming language, and some other dependencies.

  • Debian-based:

    sudo apt update
sudo apt install -y golang-go debootstrap rsync gpg squashfs-tools git make build-essential

  • ArchLinux-based:

    sudo pacman -Syu
sudo pacman -S go debootstrap rsync gnupg squashfs-tools git make --needed

  • Red Hat-based:

    sudo dnf check-update
sudo dnf install golang debootstrap rsync gnupg2 squashfs-tools git make

NOTE: Distrobuilder requires Go 1.21 or higher, if your distribution doesn’t have a recent enough version available, get it from upstream.

Adhere to the following convention:

  • File inclusion does not work on GitHub. Therefore, always add a comment linking to the included file.

  • To select parts of the text, add HTML comments for the start and end points and use :start-after: and :end-before:, if possible. You can combine :start-after: and :end-before: with :start-line: and :end-line: if required. Using only :start-line: and :end-line: is error-prone though.

Tabs

Input

Output

 

````{tabs}

```{group-tab} Tab 1

Content Tab 1
```

```{group-tab} Tab 2

Content Tab 2
```

````

Content Tab 1

Collapsible sections

There is no support for details sections in rST, but you can insert HTML to create them.

Input

Output

 
<details>
<summary>Details</summary>

Content
</details>
Details

Content

Glossary

You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file.

Input

Output

 

```{glossary}

example term
  Definition of the example term.
```
example term

Definition of the example term.

{term}`example term`

example term