MyST syntax

The Sphinx Stack supports MyST Markdown.

See the following sections for syntax help and conventions.

Note

This guide assumes that you are using the Sphinx Stack. Some of the mentioned syntax requires the Sphinx extensions enabled in the Sphinx Stack.

For general style conventions, see the Canonical Documentation Style Guide.

Headings

Input

Description

# Title

Page title and H1 heading

## Heading

H2 heading

### Heading

H3 heading

#### Heading

H4 heading

…

Further headings

Nesting

In MyST, triple backticks (```) wrap both code blocks and directives, which can cause collisions if you need to place one element inside another. To nest a code block or directive inside another, add an extra backtick to the outer element’s fences:

Input

Output

 
````{admonition} Nested code block
```python
import pathlib
```
````

Nested code block

import pathlib

Additional levels of nesting require additional backticks for each parent block.

Inline formatting

Input

Output

{guilabel}`UI element`

UI element

`code`

code

{file}`file path`

file path

{command}`command`

command

{kbd}`Key`

Key

*Italic*

Italic

**Bold**

Bold

Code blocks

Start and end a code block with three back ticks:

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

 

````
```
````



```

Terminal output

A terminal view emulates the command line experience more accurately than a code block. This is particularly useful in tutorials or guides that are terminal-heavy, or where it’s helpful to show the directory a command is run from.

To show a terminal view, use the following directive:

Input

Output

 
```{terminal}

input line 1
input line 2

output line 1
output line 2

output line 3
```
user@host:~$
input line 1 > input line 2
output line 1
output line 2

output line 3

By default, everything before the first blank line in the directive’s content is rendered as input, and any content that follows is rendered as output. The terminal directive can only display one input command, but that command can span multiple lines, as in the previous example.

To render only the output of a command, include the :output-only: flag as a directive option:

Input

Output

 
```{terminal}
:output-only:

This is rendered as output.
```

This is rendered as output.

To customize the prompt (user@host:~$ by default), specify any of the following options:

  • :user:

  • :host:

  • :dir:

Input

Output

 
```{terminal}
:user: author
:host: canonical
:dir: ~/path

input

output
```
author@canonical:~/path$
input
output

The copy button for input commands is opt-in. You must include the :copy: flag in the directive’s options for the button to be displayed.

To make the terminal scroll horizontally instead of wrapping long lines, include the :scroll: option.

For more details, refer to the sphinx-terminal README.

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
     * Sub-item
   - Item 2
1. Step 2
   1. Sub-step 1
   1. Sub-step 2

  1. Step 1

    • Item 1

      • Sub-item

    • Item 2

  2. Step 2

    1. Sub-step 1

    2. Sub-step 2

In numbered lists, use 1. for all items to generate the step numbers automatically. You can also use a higher number for the first item to start with that number.

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 reST list table syntax is usually much easier. See the Sphinx documentation for all table syntax alternatives.

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

See list tables for reference.

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

* - Header 1
  - Header 2
* - Cell 1

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

Data tables

If you have a small amount of CSV data, you can include the data in the doc source.

For example:

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

"Animal", "Number of legs", "Size"

"Worm", 0, "Small"
"Penguin", 2, "Medium"
"Horse", 4, "Large"
"Ant", 6, "Small"
"Octopus", 8, "Medium"
```

If you have a large amount of CSV data, or the data is generated by an automated process, you can include the data from a file.

For example:

```{csv-table}
:file: /reuse/animals.csv
:header-rows: 1
```

Both markups result in the following output:

Animal

Number of legs

Size

Worm

0

Small

Penguin

2

Medium

Horse

4

Large

Ant

6

Small

Octopus

8

Medium

Customize the column widths, character encoding, and so on, as described in the csv-table reference.

The Sphinx Stack can also render interactive tables, which are described in Add interactive data tables.

Notes

```{admonition} <title>
:class: <class>
```

Images

Input

Output

 
![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png)

Alt text

 
```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
   :width: 100px
   :alt: Alt text

   Figure caption
```
Alt text

Figure caption

For local pictures, start the path with / (for example, /images/image.png).

Use PNG format for screenshots and SVG format for graphics.

See Five golden rules for compliant alt text for information about how to word the alt text.

Reuse

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

Substitution

To reuse sentences or paragraphs that have little markup and special formatting, use substitutions.

Substitutions can be defined in the following locations:

Globally, in a file named reuse/substitutions.yaml that is loaded into the myst_substitutions variable in conf.py. Or if you have a limited amount of substitutions, enter them directly into the myst_substitutions variable in conf.py:

conf.py
import os
import yaml

if os.path.exists('./reuse/substitutions.yaml'):
    with open('./reuse/substitutions.yaml', 'r') as fd:
        myst_substitutions = yaml.safe_load(fd.read())
else:
    myst_substitutions = {
        "version_number": "0.1.0",
        "formatted_text": "*Multi-line* text\n that uses basic **markup**.",
        "site_link": "[Website link](https://example.com)"
  }
reuse/substitutions.yaml
# Key/value substitutions to use within the Sphinx doc.
{version_number: "0.1.0",
  formatted_text: "*Multi-line* text\n that uses basic **markup**.",
  site_link: "[Website link](https://example.com)"}

Locally, putting the definitions at the top of a single file in the following format:

---
myst:
  substitutions:
    version_number: "0.1.0"
    formatted_text: "*Multi-line* text
                      that uses basic **markup**."
    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.

The definitions from the above examples are rendered as follows:

Input

Output

{{version_number}}

0.1.0

{{formatted_text}}

Multi-line text that uses basic markup.

{{site_link}}

Website link

{{advanced_reuse_key}}

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

Content isn’t substituted on GitHub, so use substitution names that indicate the included content (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.

To select parts of the text in a file, use :start-after: and :end-before: if possible. You can combine those with :start-line: and :end-line: if the same text occurs more than once. Using only :start-line: and :end-line: is error-prone though.

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

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

Input

Output

 
```{include} /how-to/index.rst
    :start-after: .. _how-to-guides:
    :end-before: =============
```

How-to guides

File inclusion does not work on GitHub, so you should always add a comment linking to the included file.

Files that only contain text that is reused somewhere else should be placed in the reuse directory and end with the extension .txt to distinguish them from normal content files.

To make sure inclusions don’t break, consider adding HTML comments (<!-- some comment -->) to the source file as markers for starting and ending.

Tabs

The recommended way of creating tabs is with the Sphinx design extension.

Input

Output

 

````{tab-set}

```{tab-item} Tab 1
:sync: key1

Content Tab 1
```

```{tab-item} Tab 2
:sync: key2

Content Tab 2
```

````

Content Tab 1

Content Tab 2

Collapsible sections

There is no support for details sections in MyST, 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 so they can then be referenced from any file.

Input

Output

 

```{glossary}

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

Definition of the example term.

{term}`MyST example term`

MyST example term

More useful markup

Input

Output

Description

 

```{versionadded} X.Y
```

Added in version X.Y.

Can be used to distinguish between different versions.

 
---

A horizontal line

Can be used to visually divide sections on a page.

 
<!-- This is a comment -->

Not visible in the output.

 
{abbr}`API (Application Programming Interface)`

API

Hover to display the full term.

 
{spellexception}`PurposelyWrong`

PurposelyWrong

Explicitly exempt a term from the spelling check.

 
---
myst:
  html_meta:
    description: Your description of the page.
---

Not displayed

Set a custom HTML meta description in the MyST Markdown front matter at the top of the document. Don’t put newlines in the description.