The basics#

Default file formats#

As well as writing in the Sphinx default format, RestructuredText (.rst), loading myst_nb will also parse:

  • Markdown files (.md)

  • Jupyter notebooks (.ipynb)

  • MyST-NB text-based notebooks (.md + top-matter)

Custom file extensions#

You can change which file extensions are parsed by MyST-NB using the source_suffix option in your, e.g.:

extensions = ["myst_nb"]
source_suffix = {
    '.rst': 'restructuredtext',
    '.ipynb': 'myst-nb',
    '.myst': 'myst-nb',

Other notebook formats#

See the Custom Formats section, for how to integrate other Notebook formats into your build, and integration with jupytext.

MyST Markdown#

For all file formats, Markdown authoring is the backbone of MyST-NB. By default, the MyST flavour of Markdown is enabled, which extends CommonMark with RST inspired syntaxes to provide the additional functionality required for technical writing.

In particular MyST adds targets, roles and directives syntax, allowing you to utilise all available Docutils/Sphinx features:

.. _target:


.. directive-name:: argument
   :parameter: value

MyST Markdown
# Header


```{directive-name} argument
:parameter: value


See also

See the Jupyter Notebooks section, for more details on how to author Jupyter notebooks.

Text-based notebooks#

MyST-NB text-based notebooks are a special format for storing Jupyter notebooks in a text file. They map directly to a Notebook file, without directly storing the code execution outputs.

To designate a Markdown file as a text-based notebook, add the following top-matter to the start of the file:

file_format: mystnb
  name: python3

The should relate to a Jupyter kernel installed in your environment.

MyST-NB will also recognise jupytext top-matter, such as:

  name: python3
  display_name: python3
    extension: .md
    format_name: myst
    format_version: '0.13'
    jupytext_version: 1.13.8

Code cells are then designated by the code-cell directive:

:tags: [my-tag]

print("Hello world!")

and Markdown can be split into cells by the +++ break syntax:

Markdown cell 1

+++ {"tags": ["my-tag"]}

Markdown cell 2, with metadata tags

See also

See the Text-based Notebooks section, for more details on text-based notebooks, and integration with jupytext.


MyST-NB parsing, execution and rendering can be configured at three levels of specificity; globally, per file, and per notebook cell, with the most specific configuration taking precedence.

See the Configuration section, for more details on how to configure MyST-NB.