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:

At the page level to enclose instruction versions related to different releases (for example, to separate the DB19 and DB21 assembly instructions).
Within pages to divide duplicate content with tab based.
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
```

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

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:

vimeo - When possible, video content should be added to the Vimeo account and formatted with the custom Duckietown vimeo directive.
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.
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.28958267680369376

Here is an example of how to glue numbers: -0.28958267680369376 and -0.05659812872603189.

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: ../../_images/index_7_0.png . 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#

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.

MyST syntax cheat sheet

Contents

MyST syntax cheat sheet#

Headers#

Target headers#

Referencing target headers#

Quote#

Thematic break#

Line comment#

Block break#

HTML block#

Links#

Lists#

Ordered list#

Unordered list#

Tables#

Referencing tables#

Tabs#

Admonitions#

Icons#

Figures#

Framed figures#

Referencing figures#

Referencing images#

Videos#

Referencing Vimeo videos#

Referencing web videos#

Referencing local videos#

Math#

Referencing math directives#

Code#

In-line code#

Code and syntax highlighting#

Executable code#

Tags#

Gluing variables#

Gluing numbers#

Gluing visualizations#

Gluing math#

Reference documents#

Cross-book references#

Example#

How to configure#

Footnotes#

Troubleshooting#

Requirements#

Tests#

ToDos#

SEO (Search Engine Optimization)#

Citations#

PDF Slides#

Example#