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 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)
|
|
[text](relative_path)
|
[PDF documentation](../advanced/pdf)
|
|
[text](target "title")
|
[Jupyter Book](https://jupyterbook.org "JB Homepage")
|
|
<target>
|
<https://jupyterbook.org>
|
|
[text][key]
|
[Jupyter Book][intro_page]
[intro_page]: https://jupyterbook.org
|
Lists¶
Ordered list¶
Example |
Result |
---|---|
1. First item
2. Second item
1. First sub-item
|
|
1. First item
2. Second item
* First sub-item
|
|
Unordered list¶
Example |
Result |
---|---|
* First item
* Second item
* First subitem
|
|
* First item
1. First subitem
2. Second subitem
|
|
Tables¶
Syntax |
Example |
Result |
||||||
---|---|---|---|---|---|---|---|---|
| a | b |
| :--- | ---: |
| c | d |
|
| 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
```
|
|
||||||
```{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
```
|
|
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 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.
```
|
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¶
See Images and figures and Markdown files for more information.
Referencing figures¶
Syntax |
Example |
Result |
---|---|---|
{numref}`label`
|
{numref}`figure-example`is a
figure example.
|
Fig. 11 is a figure example. |
{numref}`text %s <label>`
|
{numref}`Figure %s <figure-example>`
is an example.
|
Figure 11 is an example. |
{ref}`text <label>`
|
This {ref}`figure <figure-example>`
is an example.
|
This figure 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
(4)¶\[
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
(5)¶\[z=\sqrt{x^2+y^2}\]
|
See Math and equations for more information.
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¶
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
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 |
---|---|---|
|
Cell takes up all of the horizontal space |
```{code-cell} ipython3
:tags: ["full-width"]
print("This is a test.")
```
|
|
Make output cell scrollable |
```{code-cell} ipython3
:tags: ["output_scroll"]
for ii in range(100):
print("This is a test.")
```
|
|
Move code cell to the right margin |
```{code-cell} ipython3
:tags: ["margin"]
print("This is a test.")
```
|
|
Hide cell but the display the outputs |
```{code-cell} ipython3
:tags: ["hide-input"]
print("This is a test.")
```
|
|
Hide the outputs of a cell |
```{code-cell} ipython3
:tags: ["hide-output"]
print("This is a test.")
```
|
|
Hides inputs and outputs of code cell |
```{code-cell} ipython3
:tags: ["hide-cell"]
print("This is a test.")
```
|
|
Remove the inputs of a cell |
```{code-cell} ipython3
:tags: ["remove-input"]
print("This is a test.")
```
|
|
Remove the outputs of a cell |
```{code-cell} ipython3
:tags: ["remove-output"]
print("This is a test.")
```
|
|
Remove the entire code cell |
```{code-cell} ipython3
:tags: ["remove-cell"]
print("This is a test.")
```
|
|
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.3449539181631335
Here is an example of how to glue numbers: -0.3449539181631335
and -0.04776110981685107
.
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)
This is an inline glue example of a figure: . This is an example of pasting a glued output as a block:
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:
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 References and citations 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 References and citations for more information.
- 1
This is the footnote definition.