Get Started

myst-nb is distributed as a Python package and requires no non-Python dependencies.

Use pip to install myst-nb:

pip install myst-nb

You can use the mystnb-quickstart CLI to quickly create an example Sphinx + MyST-NB project:

mystnb-quickstart my_project/docs/

or simply add myst_nb to your existing Sphinx configuration:

extensions = [
    ...,
    "myst_nb"
]

By default, MyST-NB will now parse both markdown (.md) and notebooks (.ipynb).

If you used the myst_parser extension already, remove it from the extension list to avoid conflict — it is imported by myst_nb automatically; all its options, such as myst_enable_extension, will be processed.

Begin authoring your content

Once you have finished authoring your content, you can now use the sphinx-build CLI to build your documentation, e.g.

sphinx-build -nW --keep-going -b html docs/ docs/_build/html

Tip

MyST-NB is parallel-friendly, so you can also distribute the build (and execution of notebooks) over N processes with: sphinx-build -j 4

The execution environment is the same as your Sphinx environment

Your Sphinx build shares the same environment with the notebooks you execute during a build. Ensure that you call the correct sphinx-build command when building your documentation, or the environment needed to run the notebooks may not be correct. This often happens if you see an Extension error in the build log, or an error from jupyter-cache.

See also

Check out Read the Docs for hosting and continuous deployment of documentation