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)