Once activated, the MyST-NB Sphinx extension will automatically parse both markdown (.md) and Jupyter notebooks (.ipynb) into your Sphinx site. If your markdown files have Jupytext metadata for MyST Notebooks, they will be converted to notebooks and optionally executed.

In any of these files, you may write MyST Markdown. This is an extension of CommonMark markdown that provides extra syntax for common workflows in publishing, and extension points for extra functionality.

## Writing MyST Markdown¶

MyST Markdown is a flavor of markdown that gives you full access to all of the functionality provided by Sphinx (such as roles and directives). In MyST-NB, this is provided by the MyST Parser, another Sphinx extension that MyST-NB depends on.

You can write your MyST markdown in either regular markdown files (.md) or in the markdown cells of Jupyter Notebooks (.ipynb).

Warning

If you are using MyST-NB in your documentation, do not activate myst-parser. It will be automatically activated by myst-nb.

For more information about what you can write with MyST Markdown, see the MyST Parser syntax guide.

## Write notebooks in pure markdown¶

In addition to supporting MyST Markdown inside of .md and .ipynb files, you can also write Jupyter Notebooks entirelly with markdown by using MyST Markdown Notebooks. MyST Notebooks have a similar structure to Jupyter Notebooks (.ipynb), but they are written with MyST Markdown syntax to be easier to use with text editors.

To use MyST Notebooks with myst_nb, you’ll need to add Jupytext metadata to your MyST Notebooks. See MyST Notebooks in Sphinx for more details.

## Parse extensions other than .md and .ipynb¶

You can 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',
}


## Error reporting in Sphinx¶

When Sphinx encounters and error or raises a warning, it will print the location and source file of the text that generated that error. This works slightly differently depending on whether you use markdown files or Jupyter Notebook files.

For markdown (.md) files, Sphinx will correctly report the line number that the error or warning is associated with:

source/path:4: (WARNING/2) Duplicate reference definition: abc


For Jupyter Notebook (.ipynb) files, these errors also correspond to a cell index. To allow for this, we use a special format of line number corresponding to: <CELL_INDEX> * 10000 + LINE_NUMBER.

For example, the following error corresponds to Cell 1, line 4:

source/path:10004: (WARNING/2) Duplicate reference definition: abc