0
# MyST-NB
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: myst-nb
7
- **Language**: Python
8
- **Installation**: `pip install myst-nb`
9
- **Requires**: Python >=3.9
10
11
## Core Imports
12
13
```python
14
import myst_nb
15
```
16
17
For Sphinx configuration:
18
19
```python
20
# In conf.py
21
extensions = ['myst_nb']
22
```
23
24
For gluing variables:
25
26
```python
27
from myst_nb import glue
28
```
29
30
For CLI usage:
31
32
```python
33
from myst_nb.cli import quickstart, md_to_nb
34
```
35
36
## Basic Usage
37
38
### Sphinx Extension Setup
39
40
```python
41
# In your Sphinx conf.py
42
extensions = ['myst_nb']
43
44
# Optional configuration
45
nb_execution_mode = "auto"
46
nb_execution_timeout = 30
47
```
48
49
### Gluing Variables for Cross-referencing
50
51
```python
52
from myst_nb import glue
53
import matplotlib.pyplot as plt
54
55
# Create a plot
56
fig, ax = plt.subplots()
57
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
58
59
# Glue the figure for later reference
60
glue("my_plot", fig, display=False)
61
```
62
63
Then reference in markdown:
64
```markdown
65
{glue:figure} `my_plot`
66
:name: "fig-example"
67
68
This is my plot
69
```
70
71
### Command Line Usage
72
73
```bash
74
# Create a new MyST-NB project
75
mystnb-quickstart
76
77
# Convert MyST markdown to Jupyter notebook
78
mystnb-to-jupyter input.md output.ipynb
79
80
# Generate HTML from notebook
81
mystnb-docutils-html notebook.ipynb output.html
82
```
83
84
## Architecture
85
86
MyST-NB follows a modular architecture with clear separation of concerns:
87
88
- **Parser Layer**: Handles notebook parsing and MyST markdown processing
89
- **Execution Layer**: Manages notebook execution with multiple backend strategies (direct, cached, inline)
90
- **Rendering Layer**: Converts notebook content to various output formats (HTML, LaTeX, XML)
91
- **Extension Layer**: Provides Sphinx integration and docutils compatibility
92
- **Plugin System**: Extensible renderer and MIME type handling
93
94
This design enables flexible notebook processing pipelines while maintaining compatibility with both Sphinx documentation systems and standalone docutils processing.
95
96
## Capabilities
97
98
### Sphinx Extension
99
100
Core Sphinx integration functionality including setup, configuration, parsing, rendering, and post-processing transforms for notebook content.
101
102
```python { .api }
103
def setup(app)
104
```
105
106
[Sphinx Extension](./sphinx-extension.md)
107
108
### Configuration Management
109
110
Comprehensive configuration system with 40+ options controlling execution, rendering, output formatting, and display behavior.
111
112
```python { .api }
113
class NbParserConfig:
114
execution_mode: str
115
execution_timeout: int
116
render_plugin: str
117
remove_code_source: bool
118
# ... 40+ configuration fields
119
```
120
121
[Configuration](./configuration.md)
122
123
### Notebook Reading and Processing
124
125
Reading, parsing, and processing of Jupyter notebooks in various formats including standard .ipynb and MyST markdown notebooks.
126
127
```python { .api }
128
def standard_nb_read(text: str) -> nbf.NotebookNode
129
def create_nb_reader(...) -> NbReader | None
130
def read_myst_markdown_notebook(...)
131
```
132
133
[Reading and Processing](./reading-processing.md)
134
135
### Notebook Execution
136
137
Multiple execution strategies for notebook cells including direct execution, cached execution via jupyter-cache, and inline variable evaluation.
138
139
```python { .api }
140
class NotebookClientBase
141
class ExecutionResult
142
def create_client(...) -> NotebookClientBase
143
```
144
145
[Execution](./execution.md)
146
147
### Rendering and Output
148
149
Flexible rendering system supporting multiple output formats with extensible MIME type handling and customizable renderers.
150
151
```python { .api }
152
class NbElementRenderer
153
class MimeData
154
def load_renderer(name: str) -> type[NbElementRenderer]
155
```
156
157
[Rendering](./rendering.md)
158
159
### Glue Extension
160
161
Variable gluing system for cross-referencing computed results across notebook cells and documentation, with roles and directives for content insertion.
162
163
```python { .api }
164
def glue(name: str, variable, display: bool = True) -> None
165
```
166
167
[Glue System](./glue.md)
168
169
### Download Extension
170
171
Role for downloading executed notebooks, allowing users to access processed notebook files from the documentation.
172
173
```python { .api }
174
class NbDownloadRole
175
```
176
177
### Command Line Interface
178
179
Complete command-line interface for project creation, notebook conversion, and document generation across multiple output formats.
180
181
```python { .api }
182
def quickstart(args: list[str] | None = None)
183
def md_to_nb(args: list[str] | None = None)
184
```
185
186
[Command Line Interface](./cli.md)
187
188
### Docutils Integration
189
190
Standalone docutils parser and renderer for direct notebook processing without Sphinx, enabling integration into custom documentation pipelines.
191
192
```python { .api }
193
class Parser(MystParser)
194
class DocutilsNbRenderer(DocutilsRenderer, MditRenderMixin)
195
```
196
197
[Docutils Integration](./docutils.md)