Note

This is a shortlisted version of the MyST syntax cheat sheet.

MyST syntax cheat sheet#

Headers#

Syntax

Example

Result

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
# MyST syntax cheat sheet

Level 1-6 headings, denoted by number of #

Target headers#

Syntax

Example

Result

(target_header)=
(myst_cheatsheet)=
# MyST Cheat Sheet

See below how to reference target headers.

Referencing target headers#

[](myst_cheatsheet)

You can specify the text of the target:

[MyST syntax lecture](myst_cheatsheet)

Quote#

Syntax

Example

Result

> text
> this is a quote

quoted text

Thematic break#

Syntax

Example

Result

---
This is the end of some text.

---

## New Header

Creates a horizontal line in the output

Line comment#

Syntax

Example

Result

% text
a line
% a comment
another line

See Comments for more information.

Block break#

Syntax

Example

Result

+++
This is an example of
+++ {"meta": "data"}
a block break

This is an example of

a block break

HTML block#

Syntax

Example

Result

<tagName> text </tagName>
<p> This is a paragraph </p>

This is a paragraph

Lists#

Ordered list#

Example

Result

1. First item
2. Second item
    1. First sub-item
  1. First item

  2. Second item

    1. First sub-item

1. First item
2. Second item
    * First sub-item
  1. First item

  2. Second item

    • First subitem

Unordered list#

Example

Result

* First item
* Second item
  * First subitem
  • First item

  • Second item

    • First subitem

* First item
  1. First subitem
  2. Second subitem
  • First item

    1. First subitem

    2. Second subitem

Tables#

Syntax

Example

Result

| a    | b    |
| :--- | ---: |
| c    | d    |
|    Training   |   Validation   |
| :------------ | -------------: |
|        0      |        5       |
|     13720     |      2744      |

Training

Validation

0

5

13720

2744

```{list-table} Table title
:header-rows: 1
:name: label-to-reference

* - Col1
  - Col2
* - Row1 under Col1
  - Row1 under Col2
* - Row2 under Col1
  - Row2 under Col2
```
```{list-table} This table title
:header-rows: 1
:name: example-table

* - Training
  - Validation
* - 0
  - 5
* - 13720
  - 2744
```
Table 1 This table title#

Training

Validation

0

5

13720

2744

Referencing tables#

Note

In order to reference a table, you must add a label to it. To add a label to your table simply include a :name: parameter followed by the label of your table. In order to add a numbered reference, you must also include a table title. See example above.

Syntax

Example

Result

{numref}`label`
{numref}`example-table` is an example.

Table 1 is an example.

[text](label)
This is an unnumbered ref: [table](example-table).

This is an unnumbered ref: table.

Tabs#

Tabs can be used in several ways:

  1. At the page level to enclose instruction versions related to different releases (for example, to separate the DB19 and DB21 assembly instructions).

  2. Within pages to divide duplicate content with tab based.

  3. Nested within other components such as a list.

Note

Related content that does not include some duplication should be shown in a table rather than a tab to prevent hidden text.

Example

Result

````{tab-set}

```{tab-item} DB19
This is example content for the DB19
```

```{tab-item} DB21
This is example content for the DB21
```
````

This is example content for the DB19

This is example content for the DB21

Admonitions#

Syntax

Result

```{note}
Use note directives for basic highlighting.
```

Note

Use note directives for basic highlighting.

```{warning}
Use warnings for situations that might 
cause harm, but can be fixed.
```

Warning

Use warnings for situations that might cause harm, but can be fixed.

```{tip}
A tip is a useful suggestion for the reader.
```

Tip

A tip is a useful suggestion for the reader.

```{attention}
This directive should be used to
highlight particularly tricky steps.
```

Attention

This directive should be used to highlight particularly tricky steps.

```{danger}
Used for situations that might 
cause irreparable harm (to people or robots).
```

Danger

Used for situations that might cause irreparable harm (to people or robots).

```{seealso}
Used for external links (to
third-party websites or other documents).
```

See also

Used for external links (to third-party websites or other documents).

All above specific admonitions are specific pre-made directives. You could make an admonition with custom title and class with the example below.

```{admonition} Title
text
```
```{admonition} General admonition
content
```

General admonition

content

```{admonition} Title
:class: warning
text
```
```{admonition} This is a title
:class: warning
A custom admonition
```

This is a title

A custom admonition

Icons#

Icons are provided by the font-awesome project. The complete list of icons available can be found here.

Syntax

Example

Result

```{icon} <icon-id>
```
```{icon} ice-cream
```

Figures#

Syntax

Example

Result

```{figure} ./path/to/figure.jpg
:name: label

caption
```
```{figure} ../../_images/duckietown.jpeg
:width: 50px
:name: figure-example-2

Here is my figure caption!
```
../../_images/duckietown.jpeg

Fig. 6 Here is my figure caption!#

```{image} ./path/to/figure.jpg
:name: label
```
```{image} ../../_images/duckietown.jpeg
:scale: 20%
:align: center
:name: image-example
```
../../_images/duckietown.jpeg
![alt-text](path/to/image)
![](https://tinyurl.com/39ewhkab)

Framed figures#

Use the :class: framed parameter to add a border around the image.

Syntax

Example

Result

```{figure} ./path/to/figure.jpg
:class: framed
```
```{figure} ../../_images/duckietown.jpeg
:width: 50px
:class: framed
```
../../_images/duckietown.jpeg

Note

  • Content/caption is not permitted for images, but only available for figures.

  • Settings are not available with ![alt-text](path/to/image) format

Referencing figures#

Syntax

Example

Result

{numref}`label`
{numref}`figure-example-2`is a
figure example.

Fig. 6 is a figure example.

{numref}`text %s <label>`
{numref}`Figure %s <figure-example-2>`
is an example.

Figure 6 is an example.

[text]<label>
This [figure](figure-example-2)
is an example.

This figure is an example.

Referencing images#

Syntax

Example

Result

[text](label)
This [image](image-example)
is an example.

This image is an example.

Videos#

Videos can be referenced using the following methods:

  1. vimeo - When possible, video content should be added to the Vimeo account and formatted with the custom Duckietown vimeo directive.

  2. videoembed - For other video content accessible via a web link, use the videoembed directive. All iframe attributes are available mimicking the :alt: parameter syntax below.

  3. video - For videos stored locally to the book project (this is not recommended), use the video directive. All iframe attributes are available mimicking the :alt: parameter syntax below.

Referencing Vimeo videos#

Syntax

Example

Result

```{vimeo} video-id
:alt: alt text
```
```{vimeo} 527022343
:alt: alt text
```

Referencing web videos#

Syntax

Example

Result

```{video} embed_link
:alt: alt text
```
```{video} https://www.youtube.com/embed/mXH1u885bn8
:alt: alt text
```

Referencing local videos#

This is not recommended - please host your video content on Vimeo or another online service rather than in the book project. If absolutely necessary, you can include local videos with custom formatting using the video directive.

Supported file types: .mp4, .ogm, .ogv, .ogg, .webm.

Syntax

Example

Result

```{video} file_path 
:alt: alt
```
```{video} ../assets/videos/my_video.mp4
:alt: alt text
```

Math#

Syntax

Example

Result

Inline

This is an example of an
inline equation $z=\sqrt{x^2+y^2}$.

This is an example of an inline equation \(z=\sqrt{x^2+y^2}\).

Math blocks

This is an example of a
math block

$$
z=\sqrt{x^2+y^2}
$$

This is an example of a math block

\[ z=\sqrt{x^2+y^2} \]

Math blocks with labels

This is an example of a
math block with a label

$$
z=\sqrt{x^2+y^2}
$$ (eq-label)

This is an example of a math block with a label

(1)#\[ z=\sqrt{x^2+y^2} \]

Referencing math directives#

Syntax

Example

Result

[](label)
Check out equation [](eq-label).

Check out equation (1).

Code#

In-line code#

Example:

Wrap in-line code blocks in backticks: `boolean example = true;`.

Result:

Wrap in-line code blocks in backticks: boolean example = true;.

Code and syntax highlighting#

Example:

```python
note = "Python syntax highlighting"
print(node)
```

or

```none
No syntax highlighting.
```

Result:

note = "Python syntax highlighting"
print(node)

or

No syntax highlighting.

Executable code#

Warning

Make sure to include this front-matter YAML block at the beginning of your .ipynb or .md files.

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

Example:

```{code-cell} ipython3
note = "Python syntax highlighting"
print(note)
```

Result:

note = "Python syntax highlighting"
print(note)
Python syntax highlighting

Tags#

See the tags section on Jupyter Books documentation. For formatting the code cells.

Gluing variables#

Example:

```{code-cell} ipython3
from myst_nb import glue
my_variable = "here is some text!"
glue("glued_text", my_variable)
```

Here is an example of how to glue text: {glue:}`glued_text`

Result:

from myst_nb import glue
my_variable = "here is some text!"
glue("glued_text", my_variable)
'here is some text!'

Here is an example of how to glue text: 'here is some text!'

Gluing numbers#

Example:

```{code-cell} ipython3
from myst_nb import glue
import numpy as np
import pandas as pd

ss = pd.Series(np.random.randn(4))
ns = pd.Series(np.random.randn(100))

glue("ss_mean", ss.mean())
glue("ns_mean", ns.mean(), display=False)
```

Here is an example of how to glue numbers: {glue:}`ss_mean` and {glue:}`ns_mean`.

Result:

from myst_nb import glue
import numpy as np
import pandas as pd

ss = pd.Series(np.random.randn(4))
ns = pd.Series(np.random.randn(100))

glue("ss_mean", ss.mean())
glue("ns_mean", ns.mean(), display=False)
/usr/local/lib/python3.8/dist-packages/pandas/core/computation/expressions.py:20: UserWarning: Pandas requires version '2.7.3' or newer of 'numexpr' (version '2.7.1' currently installed).
  from pandas.core.computation.check import NUMEXPR_INSTALLED
0.8429663063412121

Here is an example of how to glue numbers: 0.8429663063412121 and 0.03295270618585206.

Gluing visualizations#

Example:

```{code-cell} ipython3
from myst_nb import glue
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 200)
y = np.sin(x)
fig, ax = plt.subplots()
ax.plot(x, y, 'b-', linewidth=2)

glue("glued_fig", fig, display=False)
```

This is an inline glue example of a figure: {glue:}`glued_fig`.
This is an example of pasting a glued output as a block:
```{glue:} glued_fig
```

Result:

from myst_nb import glue
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 200)
y = np.sin(x)
fig, ax = plt.subplots()
ax.plot(x, y, 'b-', linewidth=2)

glue("glued_fig", fig, display=False)
../../_images/index_7_1.png

This is an inline glue example of a figure: ../../_images/index_7_0.png. This is an example of pasting a glued output as a block:

../../_images/index_7_0.png

Gluing math#

Example:

```{code-cell} ipython3
import sympy as sym
x, y = sym.symbols('x y')
z = sym.Function('z')
z = sym.sqrt(x**2+y**2)
glue("example_eq", z, display=False)
```

To glue a math equation try
```{glue:math} example_eq
:label: glue-eq-example
```

Result:

import sympy as sym
x, y = sym.symbols('x y')
z = sym.Function('z')
z = sym.sqrt(x**2+y**2)
glue("example_eq", z, display=False)

To glue a math equation try:

()#\[\displaystyle \sqrt{x^{2} + y^{2}}\]

Reference documents#

Syntax

Example

Result

[](path/to/document)
Ref to [](../style/index)

Ref to Style guide

[text](path/to/document)
See [here](../style/index)
for more information.

See here for more information.

Cross-book references#

The cross-book referencing is achieved using the intersphinx plugin for sphinx. For a cross-book reference, you need to know the book name and the label defined within that book.

Note

All books hosted on docs.duckietown.com are automatically made available to be linked from any other Duckietown book. The book name is the repository name.

Example#

Link to a [page on another book](book-opmanual-duckiebot:duckiebot-boot).

How to configure#

The mapping between book names and their remote location is defined in the _config.yml file. For example, we can add a link to the book jupyter-book-docs as follows,

sphinx:
  ...
  config:
    intersphinx_mapping:
      jupyter-book-docs:
        - "https://jupyterbook.org/en/stable"
        - null

Footnotes#

Syntax

Example

Result

[^ref]

[^ref]: Footnote text
This is a footnote reference.[^myref]

[^myref]: This **is** the footnote definition.

This is a footnote reference.1

Troubleshooting#

Troubleshooting cards can be created using the {trouble} directive.

Syntax

Example

```{trouble}
symptom here
---
resolution here
```

Troubleshooting

SYMPTOM

I do not see a camera image.

RESOLUTION

Make sure the camera cable is plugged in.

Requirements#

Requirements/outputs cards can be created using the {needget} directive.

Syntax

Example

```{needget}
* Requirement 1
* Requirement 2
---
* Output 1
```

What you will need

  • Duckie

  • Robot

What you will get

  • Duckiebot

Tests#

You can use the Test / What to Expect card (testexpect) to define checkpoints after book instructions.

Syntax

Result

```{testexpect}
Test
---
Expect
```

Test

pip3 --version

Expected Result

This command should output a version number for the pip3 package.

ToDos#

You can drop ToDos throughout the documentation using the {todo} directive. ToDos are rendered only on the staging documentation, they are hidden in production.

Syntax

Example

```{todo}
todo message here
```

SEO (Search Engine Optimization)#

You can use the seo directive to set SEO metadata for the page. For example, you can set a page description and a set of keywords as shown in the example below.

Syntax

```{seo}
:description: A description for the page
:keywords: word1,word2,word3
```

Citations#

Note

Make sure you have a reference bibtex file. And it is included in the _config.yml, under bibtex_bibfiles section.

Syntax

Example

Result

{cite}`mybibtexcitation`
An example citation {cite}`tani2016`.

An example citation [TPZ+17].

And, at the bottom of the page, include the list of references:

```{bibliography}
:filter: docname in docnames
```
TPZ+17

Jacopo Tani, Liam Paull, Maria T. Zuber, Daniela Rus, Jonathan How, John Leonard, and Andrea Censi. Duckietown: an innovative way to teach autonomy. In Dimitris Alimisis, Michele Moro, and Emanuele Menegatti, editors, Educational Robotics in the Makers Era, 104–121. Cham, 2017. Springer International Publishing.

PDF Slides#

Use the following syntax to create an embedded rendering of a PDF slide deck.

```{slides} <LOCATION>
```

where <LOCATION> can be a relative path to a PDF file in the book repository or an absolute URL to an external PDF file.

Example#

Note

The slides viewer DOES NOT work in local builds of a book.


1

This is the footnote definition.