MyST Cheat Sheet

Headers

Syntax

Example

Note

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
# MyST Cheat Sheet

Level 1-6 headings, denoted by number of #

Target Headers

Syntax

Example

Note

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

See below how to reference target headers.

Referencing Target Headers

Targets can be referenced with the ref inline role which by default uses the section title:

{ref}`myst_cheatsheet`

You can specify the text of the target:

{ref}`MyST syntax lecture <myst_cheatsheet>`

Another alternative is to use markdown syntax:

[MyST syntax lecture](myst_cheatsheet)

Quote

Syntax

Example

Note

> text
> this is a quote

quoted text

Thematic Break

Syntax

Example

Note

---
This is the end of some text.

---

## New Header

Creates a horizontal line in the output

Line Comment

Syntax

Example

Note

% 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}
:header-rows: 1

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

* - Training
  - Validation
* - 0
  - 5
* - 13720
  - 2744
```

Training

Validation

0

5

13720

2744

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

* - Col1
  - Col2
* - Row1 under Col1
  - Row1 under Col2
* - Row2 under Col1
  - Row2 under Col2
```
 ```{list-table} Table with a title
:header-rows: 1

* - Training
  - Validation
* - 0
  - 5
* - 13720
  - 2744
```
Table 2 Table with a title

Training

Validation

0

5

13720

2744

Referencing Tables

Note

To add a label to your table simply include a :name: parameter followed by the label of your table. See example above.

Syntax

Example

Result

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

Table 1 is an example.

{ref}`text <label>`
This {ref}`table <example-table>` is an example.

This table is an example.

{numref}`text %s <label>`
{numref}`Tbl %s <example-table>` is an example.

Tbl 1 is an example.

Admonitions

Syntax

Example

Result

```{admonition} Title
text
```
```{admonition} This is a title
An example of an admonition with a title.
```

This is a title

An example of an admonition with a title.

```{note}
text
```

or

```{note} text
some more text...
```
```{note} Notes require **no** arguments,
so content can start here.
```

Note

Notes require no arguments, so content can start here.

```{warning} text
some more text...
```
```{warning} This is an example
of a warning directive.
```

Warning

This is an example of a warning directive.

```{tip} text
some more text...
```
```{tip} This is an example
of a tip directive.
```

Tip

This is an example of a tip directive.

```{caution} text
some more text...
```
```{caution} This is an example
of a caution directive.
```

Caution

This is an example of a caution directive.

```{attention} text
some more text...
```
```{attention} This is an example
of an attention directive.
```

Attention

This is an example of an attention directive.

```{danger} text
some more text...
```
```{danger} This is an example
of a danger directive.
```

Danger

This is an example of a danger directive.

```{error} text
some more text...
```
```{error} This is an example
of an error directive.
```

Error

This is an example of an error directive.

```{hint} text
some more text...
```
```{hint} This is an example
of a hint directive.
```

Hint

This is an example of a hint directive.

```{important} text
some more text...
```
```{important} This is an example
of an important directive.
```

Important

This is an example of an important directive.

Figures and Images

Syntax

Example

Result

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

caption
```
```{figure} ../images/C-3PO_droid.png
:height: 150px
:name: figure-example

Here is my figure caption!
```
../_images/C-3PO_droid2.png

Fig. 8 Here is my figure caption!

```{image} ./path/to/figure.jpg
:name: label
```
```{image} ../images/C-3PO_droid.png
:height: 150px
:name: image-example
```
../_images/C-3PO_droid2.png

See Figures and Markdown files for more information.

Referencing Figures

Syntax

Example

Result

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

Fig. 8 is a figure example.

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

Figure 8 is an example.

{ref}`text <label>`
This {ref}`figure <figure-example>`
is an example.

This figure is an example.

Referencing Images

Syntax

Example

Result

{ref}`text <label>`
This {ref}`image <image-example>`
is an example.

This image is an example.

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}
$$ (mylabel)

This is an example of a math block with a label

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

Math directives

This is an example of a
math directive with a
label
```{math}
:label: eq-label

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

This is an example of a math directive with a label

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

See Math and Equations for more information.

Referencing Math Directives

Syntax

Example

Result

{eq}`label`
Check out equation {eq}`eq-label`.

Check out equation (3).

Code

Inline Code

Example:

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

Result:

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

Code and Syntax Highlighting

Example:

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

or

```
No syntax highlighting if no language
is indicated.
```

Result:

note = "Python syntax highlighting"
print(node)

or

No syntax highlighting if no language
is indicated.

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
    format_version: '0.8'
    jupytext_version: 1.4.1+dev
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

See Notebooks written entirely in markdown for more information.

Tags

The following tags can be applied to code cells by introducing them as options:

Tag option

Description

Example

"full-width"

Cell takes up all of the horizontal space

```{code-cell} ipython3
:tags: ["full-width"]
print("This is a test.")
```

"output_scroll"

Make output cell scrollable

```{code-cell} ipython3
:tags: ["output_scroll"]
for ii in range(100):
  print("This is a test.")
```

"margin"

Move code cell to the right margin

```{code-cell} ipython3
:tags: ["margin"]
print("This is a test.")
```

"hide-input""

Hide cell but the display the outputs

```{code-cell} ipython3
:tags: ["hide-input""]
print("This is a test.")
```

"hide-output"

Hide the outputs of a cell

```{code-cell} ipython3
:tags: ["hide-output"]
print("This is a test.")
```

"hide-cell"

Hides inputs and outputs of code cell

```{code-cell} ipython3
:tags: ["hide-cell"]
print("This is a test.")
```

"remove-input"

Remove the inputs of a cell

```{code-cell} ipython3
:tags: ["remove-input"]
print("This is a test.")
```

"remove-output"

Remove the outputs of a cell

```{code-cell} ipython3
:tags: ["remove-output"]
print("This is a test.")
```

"remove-cell"

Remove the entire code cell

```{code-cell} ipython3
:tags: ["remove-cell"]
print("This is a test.")
```

"raises-exception"

Mark cell as “expected to error”

```{code-cell} ipython3
:tags: ["raises-exception"]
while True print('Hello world')
```

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!'

See Gluing variables in your notebook for more information.

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

Here is an example of how to glue numbers: 0.02534716454793782 and -0.029520784155990954.

See Gluing variables in your notebook for more information.

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/cheatsheet_7_1.png

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

../_images/cheatsheet_7_0.png

See Gluing variables in your notebook for more information.

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}}\]

See Insert code outputs into page content for more information.

Reference Documents

Syntax

Example

Result

{doc}`path/to/document`
See {doc}`../content/citations`
for more information.

See Citations and cross-references for more information.

{doc}`text <path/to/document>`
See {doc}`here <../content/citations>`
for more information.

See here for more information.

Footnotes

Syntax

Example

Result

[^ref]

[^ref]: Footnote text
This is an example of a footnote.[^footnote1]

[^footnote1]: The definition for referencing
 footnotes is generally placed at the bottom
 of the document.

This is a footnote reference.1

See Footnotes for more information.

Citations

Note

Make sure you have a reference bibtex file. You can create one by running touch references.bib or view a references.bib example.

Syntax

Example

Result

{cite}`mybibtexcitation`
This example generates the following
citation {cite}`perez2011python`.

This example generates the following citation [PGH11].

To include a list of citations mentioned in the document, introduce the bibliography directive

```{bibliography} ../references.bib
:filter: docname in docnames
```

See Citations and cross-references for more information.


1

This is the footnote definition.