MyST-NB

A comprehensive Sphinx extension and docutils parser for Jupyter notebooks containing MyST Markdown. MyST-NB bridges the gap between interactive notebook development and static documentation systems, enabling seamless integration of executable notebooks into documentation workflows with full support for code execution, output rendering, and cross-referencing.

Package Information

• Package Name: myst-nb
• Language: Python
• Installation: pip install myst-nb
• Requires: Python >=3.9

Core Imports

import myst_nb

For Sphinx configuration:

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

For gluing variables:

from myst_nb import glue

For CLI usage:

from myst_nb.cli import quickstart, md_to_nb

Basic Usage

Sphinx Extension Setup

# In your Sphinx conf.py
extensions = ['myst_nb']

# Optional configuration
nb_execution_mode = "auto"
nb_execution_timeout = 30

Gluing Variables for Cross-referencing

from myst_nb import glue
import matplotlib.pyplot as plt

# Create a plot
fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])

# Glue the figure for later reference
glue("my_plot", fig, display=False)

Then reference in markdown:

{glue:figure} `my_plot`
:name: "fig-example"

This is my plot

Command Line Usage

# Create a new MyST-NB project
mystnb-quickstart

# Convert MyST markdown to Jupyter notebook
mystnb-to-jupyter input.md output.ipynb

# Generate HTML from notebook
mystnb-docutils-html notebook.ipynb output.html

Architecture

MyST-NB follows a modular architecture with clear separation of concerns:

• Parser Layer: Handles notebook parsing and MyST markdown processing
• Execution Layer: Manages notebook execution with multiple backend strategies (direct, cached, inline)
• Rendering Layer: Converts notebook content to various output formats (HTML, LaTeX, XML)
• Extension Layer: Provides Sphinx integration and docutils compatibility
• Plugin System: Extensible renderer and MIME type handling

This design enables flexible notebook processing pipelines while maintaining compatibility with both Sphinx documentation systems and standalone docutils processing.

Capabilities

Sphinx Extension

Core Sphinx integration functionality including setup, configuration, parsing, rendering, and post-processing transforms for notebook content.

def setup(app)

Sphinx Extension

Configuration Management

Comprehensive configuration system with 40+ options controlling execution, rendering, output formatting, and display behavior.

class NbParserConfig:
    execution_mode: str
    execution_timeout: int
    render_plugin: str
    remove_code_source: bool
    # ... 40+ configuration fields

Configuration

Notebook Reading and Processing

Reading, parsing, and processing of Jupyter notebooks in various formats including standard .ipynb and MyST markdown notebooks.

def standard_nb_read(text: str) -> nbf.NotebookNode
def create_nb_reader(...) -> NbReader | None
def read_myst_markdown_notebook(...)

Reading and Processing

Notebook Execution

Multiple execution strategies for notebook cells including direct execution, cached execution via jupyter-cache, and inline variable evaluation.

class NotebookClientBase
class ExecutionResult
def create_client(...) -> NotebookClientBase

Execution

Rendering and Output

Flexible rendering system supporting multiple output formats with extensible MIME type handling and customizable renderers.

class NbElementRenderer
class MimeData
def load_renderer(name: str) -> type[NbElementRenderer]

Rendering

Glue Extension

Variable gluing system for cross-referencing computed results across notebook cells and documentation, with roles and directives for content insertion.

def glue(name: str, variable, display: bool = True) -> None

Glue System

Download Extension

Role for downloading executed notebooks, allowing users to access processed notebook files from the documentation.

class NbDownloadRole

Command Line Interface

Complete command-line interface for project creation, notebook conversion, and document generation across multiple output formats.

def quickstart(args: list[str] | None = None)
def md_to_nb(args: list[str] | None = None)

Command Line Interface

Docutils Integration

Standalone docutils parser and renderer for direct notebook processing without Sphinx, enabling integration into custom documentation pipelines.

class Parser(MystParser)
class DocutilsNbRenderer(DocutilsRenderer, MditRenderMixin)

Docutils Integration