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

Links

Syntax	Example	Result
[text](target)	[Jupyter Book](https://jupyterbook.org)	Jupyter Book
[text](relative_path)	[Another page](../style/index)	Another page
<target>	<https://jupyterbook.org>	https://jupyterbook.org
[text][key]	[Jupyter Book][intro_page] [intro_page]: https://jupyterbook.org	Jupyter Book

Lists

Ordered list

Example	Result
1. First item 2. Second item 1. First sub-item	First item Second item First sub-item
1. First item 2. Second item * First sub-item	First item 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 First subitem 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 ``` ````	DB19 This is example content for the DB19 DB21 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! ```	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 ```
	

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 ```

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)

-0.41993333010914624

Here is an example of how to glue numbers: -0.41993333010914624 and 0.0982900937960647.

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)

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

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).

Link to a page on another book.

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

Advanced: list all labels for a given book

To conveniently find the available labels in other books, a utility comes with jupyter-book installation. Take the above linked book for example:

python -m sphinx.ext.intersphinx https://jupyterbook.org/en/stable/objects.inv

Or, use it in a script (example outcomes provided below)

from sphinx.ext.intersphinx import inspect_main
inspect_main(["https://jupyterbook.org/en/stable/objects.inv"])

Footnotes

Note

Footnotes are displayed at the very bottom of the page.

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 ```

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.