Using different parsers¶
Technically, you can use any parser for your content, but this theme was tested with reStructuredText (default one), MyST (very popular one) and with Jupyter Notebook (ipynb).
You don’t need to configure theme in any specific way to use any of them, as it should be parser-agnostic, but we do recommend using Notebooks for interactive content and MyST with colon-fence extension enabled.
Using MyST¶
If you prefer writing documentation in a format that is closer to Markdown, you can use MyST, a dialect of Markdown for Sphinx. It’s pretty mature at this point and allows you to do everything you could do with reST anyways.
To get started with it, add the myst-parser
package to your docs:
uv add --group=docs myst-parser
# or
pip install myst-parser
And activate it in your conf.py:
extensions = [..., 'myst_parser']
You can optionally activate the colon fence syntax extension too:
myst_enable_extensions = ['colon_fence']
That’s it! Now you’re ready to write documentation
in MyST, just add files as you usually would, but
with .md extension.
Using Jupyter Notebooks¶
This theme provides styles for various Jupyter-related
extensions, including nbsphinx, which adds support for
ipynb files.
If you want to include those in your documentation as
pages, you can install the nbsphinx extension:
uv add --group=docs nbsphinx
# or
pip install nbsphinx
And then activate it in your conf.py:
extensions = [..., 'nbsphinx']
That’s it! Now you’re ready to use your notebooks,
just add files as you usually would, but with
.ipynb extension.