Notebooks as Markdown¶
MyST-NB also provides functionality for writing notebooks in a text-based format, utilising the MyST Markdown format outlined in jupytext.1 These files have a 1-to-1 mapping with the notebook, so can be opened as notebooks in Jupyter Notebook and Jupyter Lab (with jupytext installed), and are also integrated directly into the Execution and Caching machinery!
Jupytext metadata¶
In order to signal MyST-NB that it should treat your markdown file as a notebook, add the following Jupytext front-matter to the beginnign of the markdown file.
---
jupytext:
text_representation:
format_name: myst
kernelspec:
display_name: Python 3
name: python3
---
Note that kernelspec:
should map on to the kernel you wish to use to run your
notebook’s code. It must be installed on the machine and registered with Jupyter to
be used.
Tip
Jupytext allows you to convert back-and-forth between .ipynb
and MyST-markdown
notebooks.
To convert
.ipynb
to MyST-markdown, run:jupytext notebook.ipynb --to myst
To convert MyST-markdown to
.ipynb
, run:jupytext mystfile.md --to ipynb
Supported source files¶
By default the myst_nb
extension will look for both .ipynb
and .md
file extensions,
treating markdown files with the above front matter as notebooks, and as standard
markdown files otherwise. You can also change which files are parsed by MyST-NB using
the source_suffix
option in your conf.py
, e.g.:
extensions = ["myst_nb"]
source_suffix = {
'.rst': 'restructuredtext',
'.ipynb': 'myst-nb',
'.myst': 'myst-nb',
}
Syntax for code cells¶
When writing notebooks in pure-markdown, use the following syntax to define a code cell:
```{code-cell} ipython3
a = "This is some"
b = "Python code!"
print(f"{a} {b}")
```
The argument after {code-cell}
(above, ipython3
) is optional, and is used for
readability purposes. The content inside {code-cell}
makes up the content of the cell,
and will be executed at build time.
This will result in the following output after building your site:
a = "This is some"
b = "Python code!"
print(f"{a} {b}")
This is some Python code!
Parameterizing your code cell¶
You can begin your code-cell
block with front-matter metadata. These will be used
as cell-level metadata in the resulting notebook cell.
The same metadata tags can be used as you would in a normal notebook,
for example those discussed in Hiding code cells:
```{code-cell} ipython3
:tags: [hide-output]
for i in range(20):
print("Millhouse did not test cootie positive")
```
Yields the following:
for i in range(20):
print("Millhouse did not test cootie positive")
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
Millhouse did not test cootie positive
and raises-exception
means our code will execute without halting the kernel:
```{code-cell} ipython3
:tags: [raises-exception]
raise ValueError("oopsie!")
```
raise ValueError("oopsie!")
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
<ipython-input-3-d0e73a979db8> in <module>
----> 1 raise ValueError("oopsie!")
ValueError: oopsie!
- 1
This notebook can be downloaded as markdown.ipynb and
markdown.md