MyST syntax 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 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)

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

Links¶

Syntax	Example	Result
[text](target)	[Jupyter Book](https://jupyterbook.org)	Jupyter Book
[text](relative_path)	[PDF documentation](../advanced/pdf)	PDF documentation
[text](target "title")	[Jupyter Book](https://jupyterbook.org "JB Homepage")	Jupyter Book
<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}
: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
```

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

表 3 This table title¶
Training	Validation
0	5
13720	2744

Referencing tables¶

注解

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.	表 2 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 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. ```	注解 Notes require no arguments, so content can start here.
```{warning} text some more text... ```	```{warning} This is an example of a warning directive. ```	警告 This is an example of a warning directive.
```{tip} text some more text... ```	```{tip} This is an example of a tip directive. ```	小技巧 This is an example of a tip directive.
```{caution} text some more text... ```	```{caution} This is an example of a caution directive. ```	小心 This is an example of a caution directive.
```{attention} text some more text... ```	```{attention} This is an example of an attention directive. ```	注意 This is an example of an attention directive.
```{danger} text some more text... ```	```{danger} This is an example of a danger directive. ```	危险 This is an example of a danger directive.
```{error} text some more text... ```	```{error} This is an example of an error directive. ```	错误 This is an example of an error directive.
```{hint} text some more text... ```	```{hint} This is an example of a hint directive. ```	提示 This is an example of a hint directive.
```{important} text some more text... ```	```{important} This is an example of an important directive. ```	重要 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!
```

图 12 Here is my figure caption!¶

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

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

See image 和 figure and Markdown 文件 for more information.

Referencing figures¶

Syntax

Example

Result

{numref}`label`

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

图 12 is a figure example.

{numref}`text %s <label>`

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

Figure 12 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 (6)¶\[ 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 (7)¶\[z=\sqrt{x^2+y^2}\]

See 数学和公式 for more information.

Referencing math directives¶

Syntax	Example	Result
{eq}`label`	Check out equation {eq}`eq-label`.	Check out equation (7).

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

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

警告

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 完全用 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 把变量 glue 在你的笔记本上 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.34036806387937946

Here is an example of how to glue numbers: 0.34036806387937946 and 0.0676144517139834.

See 把变量 glue 在你的笔记本上 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)

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:

See 把变量 glue 在你的笔记本上 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 存储代码输出并插入到内容中 for more information.

Reference documents¶

Syntax	Example	Result
{doc}`path/to/document`	See {doc}`../content/citations` for more information.	See 引用和参考书目 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¶

注解

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 [Perez et al., 2011].

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

```{bibliography}
:filter: docname in docnames
```

See 引用和参考书目 for more information.

1: This is the footnote definition.