MyST-NB

Warnings

• breaking Breaking changes were introduced in v1.0.0, including significant changes to configuration option names. Many options that previously did not have a prefix now use `nb_` (e.g., `jupyter_execute_notebooks` became `nb_execution_mode`). `nb_render_priority` was removed and replaced by `nb_mime_priority_overrides` with a different format. The `dollarmath` MyST extension is no longer enabled by default.
  Fix: Review the MyST-NB v1.0.0 changelog and documentation for updated configuration options. Update your `conf.py` to use the new `nb_` prefixed options and explicitly enable `dollarmath` if needed: `myst_enable_extensions = ["dollarmath"]`. For cell-level configuration, the top-level key `render` has been deprecated in favor of `mystnb`.
• breaking The `ipywidgets` package was removed as a direct dependency in v1.0.0. If your documentation relies on interactive ipywidgets, they will no longer function unless `ipywidgets` is explicitly installed in your environment.
  Fix: If your project uses `ipywidgets`, ensure it is explicitly added to your project's `requirements.txt` or installed separately: `pip install ipywidgets`.
• breaking The internal AST structure and rendering plugin system were completely rewritten in v1.0.0 for compatibility with new Docutils functionality. Any custom renderers or direct manipulation of MyST-NB's internal Docutils AST nodes will likely break.
  Fix: Custom renderers will need to be rewritten to align with the new plugin system (`myst_nb.renderers` and `myst_nb.mime_renderers` entry points). Consult the API documentation for the updated structure and plugin system.
• gotcha MyST-NB automatically activates the `myst_parser` extension. Explicitly including `myst_parser` in your `extensions` list alongside `myst_nb` will cause conflicts or redundant processing.
  Fix: Only include `'myst_nb'` in your `conf.py` `extensions` list. Do not add `'myst_parser'`. All configuration options for `myst_parser` will still be processed when `myst_nb` is active.
• gotcha When MyST-NB processes Jupyter Notebooks (.ipynb), Sphinx error reporting for these files uses a special line number format: `<CELL_INDEX> * 10000 + LINE_NUMBER`. This can make pinpointing the exact line in a notebook cell challenging without understanding the format.
  Fix: When debugging errors in `.ipynb` files, interpret `LINE_NUMBER` by taking `error_line_number % 10000`. The `CELL_INDEX` can be derived from `floor(error_line_number / 10000)`.

Install

• pip install myst-nb Install MyST-NB

Imports

• myst_nb

  extensions = ['myst_nb'] # in conf.py

  MyST-NB is primarily used as a Sphinx extension by adding 'myst_nb' to the `extensions` list in `conf.py`.
• glue

  from myst_nb import glue

  Used for 'gluing' variables from code cells into the narrative text.

Quickstart

To quickly get started, install MyST-NB and add 'myst_nb' to the `extensions` list in your Sphinx `conf.py`. You can then create MyST Markdown files (`.md`) or Jupyter Notebooks (`.ipynb`) containing code cells, which MyST-NB will parse and execute during the Sphinx build process. The `glue` function allows embedding variables directly into your narrative text.

import os

# --- conf.py (Sphinx configuration file) ---
# project = 'MyST-NB Quickstart'
# copyright = '2026, Your Name'
# extensions = [
#     'myst_nb',
#     'sphinx.ext.autodoc', # Example standard Sphinx extension
# ]
# # Optional: Configure notebook execution
# # nb_execution_mode = "auto" # 'auto', 'off', 'force', 'cache'
# # nb_execution_timeout = 60

# --- example.md (MyST Markdown file with code cells) ---
example_md_content = '''
# MyST-NB Example Document

This is a MyST Markdown file demonstrating executable code cells.

```{code-cell} python
import datetime
print("Hello from MyST-NB!")
print(f"Current time: {datetime.datetime.now()}")
```

You can also use the `glue` functionality to embed variables from executed cells.

```{code-cell} python
from myst_nb import glue
my_result = "This value was 'glued' from a Python cell."
glue("my_embedded_string", my_result)
```

The result embedded from the code cell is: {glue:text}`my_embedded_string`.
'''

# To run this, you would typically:
# 1. Create a Sphinx project (e.g., `sphinx-quickstart`)
# 2. Modify `conf.py` as commented above
# 3. Create `example.md` with the content above
# 4. Build with `sphinx-build -b html . _build`

# This snippet simulates saving the content to files for demonstration.
# In a real Sphinx project, these files would exist in your source directory.
# (Not actually running sphinx-build here, just showing file content)
print("--- Simulated conf.py content ---")
print("# See comments in code for full conf.py example")
print("extensions = ['myst_nb']")

print("\n--- Simulated example.md content ---")
print(example_md_content)