2. MyST cheat sheet

Avertissement

Not written by me (Lilian Besson)

2.1. 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 #

2.2. Target headers

Syntax

Example

Note

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

See below how to reference target headers.

2.2.1. Referencing target headers

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

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

2.3. Quote

Syntax

Example

Note

> text
> this is a quote

quoted text

2.4. Thematic break

Syntax

Example

Note

---
This is the end of some text.

---

## New Header

Creates a horizontal line in the output

2.5. Line comment

Syntax

Example

Note

% text
a line
% a comment
another line

See Comments for more information.

2.6. Block break

Syntax

Example

Result

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

This is an example of

a block break

2.7. HTML block

Syntax

Example

Result

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

This is a paragraph

2.9. Lists

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

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

2.10. 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
```
Tableau 2.1 My table title

Training

Validation

0

5

13720

2744

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

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

* - Training
  - Validation
* - 0
  - 5
* - 13720
  - 2744
```
Tableau 2.2 This table title

Training

Validation

0

5

13720

2744

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

Tableau 2.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 2.1 is an example.

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

Avertissement

This is an example of a warning directive.

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

Astuce

This is an example of a tip directive.

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

Prudence

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

Erreur

This is an example of an error directive.

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

Indication

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.

2.12. 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_droid.png

Fig. 2.1 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_droid.png

See ../content/figures and ../file-types/markdown for more information.

2.12.1. Referencing figures

Syntax

Example

Result

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

Fig. 2.1 is a figure example.

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

Figure 2.1 is an example.

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

This figure is an example.

2.12.2. Referencing images

Syntax

Example

Result

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

This image is an example.

2.13. 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.1)\[ 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

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

See ../content/math for more information.

2.13.1. Referencing math directives

Syntax

Example

Result

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

Check out equation (2.2).

2.14. Code

2.14.1. 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;.

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

2.14.3. Executable code

Avertissement

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

See ../file-types/myst-notebooks for more information.

2.14.3.1. 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')
```

2.14.4. 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 glue/gluing for more information.

2.14.5. 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.6702291145309975

Here is an example of how to glue numbers: -0.6702291145309975 and -0.062349658803514466.

See glue/gluing for more information.

2.14.6. 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/demo-myST_7_1.png

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

_images/demo-myST_7_0.png

See glue/gluing for more information.

2.14.7. 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 for more information.

2.15. Reference documents

Syntax

Example

Result

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

See ../content/citations for more information.

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

See here for more information.

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

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

PGH11

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science & Engineering, 13(2):13–21, 2011.

See ../content/citations for more information.


1

This is the footnote definition.