0
# Configuration
1

2
Comprehensive configuration system with 40+ options controlling execution, rendering, output formatting, and display behavior. The configuration system provides fine-grained control over every aspect of notebook processing.
3

4
## Capabilities
5

6
### Main Configuration Class
7

8
Central configuration dataclass that manages all MyST-NB settings with validation and type checking.
9

10
```python { .api }
11
class NbParserConfig:
12
    """
13
    Central configuration for MyST-NB notebook parsing and processing.
14
    
15
    Contains all configuration options with default values, validation,
16
    and documentation for each setting.
17
    """
18
    
19
    # File read options
20
    custom_formats: Dict[str, Tuple[str, dict, bool]] = {}
21
    read_as_md: bool = False
22
    
23
    # Configuration override keys
24
    metadata_key: str = "mystnb"
25
    cell_metadata_key: str = "mystnb"
26
    
27
    # Notebook execution options
28
    kernel_rgx_aliases: Dict[str, str] = {}
29
    eval_name_regex: str = r"^[a-zA-Z_][a-zA-Z0-9_]*$"
30
    execution_mode: Literal["off", "force", "auto", "cache", "inline"] = "auto"
31
    execution_cache_path: str = ""
32
    execution_excludepatterns: Sequence[str] = ()
33
    execution_timeout: int = 30
34
    execution_in_temp: bool = False
35
    execution_allow_errors: bool = False
36
    execution_raise_on_error: bool = False
37
    execution_show_tb: bool = False
38
    
39
    # Pre-processing options
40
    merge_streams: bool = False
41
    
42
    # Render options
43
    render_plugin: str = "default"
44
    remove_code_source: bool = False
45
    remove_code_outputs: bool = False
46
    scroll_outputs: bool = False
47
    code_prompt_show: str = "Show code cell {type}"
48
    code_prompt_hide: str = "Hide code cell {type}"
49
    number_source_lines: bool = False
50
    builder_name: str = "html"
51
    mime_priority_overrides: Sequence[Tuple[str, str, Optional[int]]] = ()
52
    output_stderr: Literal["show", "remove", "remove-warn", "warn", "error", "severe"] = "show"
53
    render_text_lexer: str = "myst-ansi"
54
    render_error_lexer: str = "ipythontb"
55
    render_image_options: Dict[str, str] = {}
56
    render_figure_options: Dict[str, str] = {}
57
    render_markdown_format: Literal["commonmark", "gfm", "myst"] = "commonmark"
58
    ipywidgets_js: Dict[str, Dict[str, str]] = ipywidgets_js_factory()
59
    
60
    # Write options for docutils
61
    output_folder: str = "build"
62
    append_css: bool = True
63
    metadata_to_fm: bool = False
64
```
65

66
### Configuration Sections
67

68
Enumeration defining different levels of configuration scope for hierarchical settings management.
69

70
```python { .api }
71
class Section(Enum):
72
    """
73
    Configuration section tags.
74
    
75
    Defines the scope and hierarchy of configuration settings:
76
    - global_lvl: Global level configuration
77
    - file_lvl: File level configuration (notebook)
78
    - cell_lvl: Cell level configuration
79
    - config: Meta configuration
80
    - read: Configuration for reading files
81
    - execute: Configuration for executing notebooks
82
    - render: Configuration for rendering notebook elements
83
    """
84
    global_lvl = "global"
85
    file_lvl = "notebook" 
86
    cell_lvl = "cell"
87
    config = "config"
88
    read = "read"
89
    execute = "execute"
90
    render = "render"
91
```
92

93
## Execution Configuration
94

95
### Execution Modes
96

97
- **`"auto"`**: Execute cells only if outputs are missing
98
- **`"force"`**: Always execute all cells
99
- **`"cache"`**: Use jupyter-cache for execution caching
100
- **`"inline"`**: Execute only inline evaluation expressions
101
- **`"off"`**: Never execute cells
102

103
### Execution Settings
104

105
```python { .api }
106
# Core execution options
107
execution_mode: str = "auto"
108
execution_timeout: int = 30  # Timeout in seconds
109
execution_show_tb: bool = False  # Show full tracebacks
110
execution_in_temp: bool = False  # Execute in temporary directory
111
execution_allow_errors: bool = False  # Continue on cell errors
112
execution_raise_on_error: bool = False  # Raise exceptions on errors
113
```
114

115
## Rendering Configuration
116

117
### Output Control
118

119
```python { .api }
120
# Code visibility
121
remove_code_source: bool = False  # Hide input code
122
remove_code_outputs: bool = False  # Hide outputs
123
remove_markdown_source: bool = False  # Hide markdown source
124

125
# Output handling
126
output_stderr: str = "show"  # "show", "remove", "remove-warn", "warn", "error"
127
merge_streams: bool = False  # Merge stdout/stderr
128
```
129

130
### MIME Type and Rendering
131

132
```python { .api }
133
# Renderer selection
134
render_plugin: str = "default"  # Renderer plugin name
135
render_priority: dict = None  # MIME type priority overrides
136

137
# Syntax highlighting
138
render_text_lexer: str = "myst-ansi"  # Lexer for text output
139
render_error_lexer: str = "ipythontb"  # Lexer for error output
140
```
141

142
### Image and Figure Options
143

144
```python { .api }
145
# Image rendering
146
render_image_options: dict = {
147
    "width": "100%",
148
    "align": "center"
149
}
150

151
# Figure rendering
152
render_figure_options: dict = {
153
    "caption": True,
154
    "numbering": True
155
}
156
```
157

158
## Advanced Configuration
159

160
### Custom Formats
161

162
```python { .api }
163
# Custom notebook formats
164
custom_formats: dict = {
165
    ".Rmd": "Rmd",
166
    ".qmd": "qmd"
167
}
168

169
# Kernel name aliases
170
kernel_rgx_aliases: dict = {
171
    "python.*": "python",
172
    "ir": "r"
173
}
174
```
175

176
### Cell-Level Configuration
177

178
Individual cells can override global configuration through cell metadata:
179

180
```json
181
{
182
    "tags": ["hide-input", "hide-output"],
183
    "mystnb": {
184
        "execution_timeout": 60,
185
        "remove_code_source": true
186
    }
187
}
188
```
189

190
## Configuration Usage Examples
191

192
### Sphinx Configuration
193

194
```python
195
# In conf.py for Sphinx
196
extensions = ['myst_nb']
197

198
# Execution settings
199
nb_execution_mode = "cache"
200
nb_execution_timeout = 120
201
nb_execution_cache_path = ".jupyter_cache"
202

203
# Display settings
204
nb_remove_code_source = False
205
nb_remove_code_outputs = False
206
nb_merge_streams = True
207
nb_output_stderr = "show"
208

209
# Rendering settings
210
nb_render_plugin = "default"
211
nb_render_image_options = {"width": "75%"}
212
nb_render_figure_options = {"align": "center"}
213
```
214

215
### Docutils Configuration
216

217
```python
218
from myst_nb.core.config import NbParserConfig
219

220
# Create configuration
221
config = NbParserConfig(
222
    execution_mode="force",
223
    execution_timeout=60,
224
    remove_code_source=True,
225
    render_text_lexer="python"
226
)
227
```
228

229
### File-Level Configuration
230

231
In MyST markdown files:
232

233
```yaml
234
---
235
mystnb:
236
  execution_mode: "force"
237
  execution_timeout: 120
238
  remove_code_source: false
239
---
240
```
241

242
### Environment-Based Configuration
243

244
```python
245
import os
246
from myst_nb.core.config import NbParserConfig
247

248
# Configure based on environment
249
config = NbParserConfig(
250
    execution_mode=os.getenv("NB_EXECUTION_MODE", "auto"),
251
    execution_timeout=int(os.getenv("NB_TIMEOUT", "30")),
252
    remove_code_source=os.getenv("NB_HIDE_CODE") == "true"
253
)
254

255
## Warning System
256

257
### Warning Types
258

259
MyST-NB provides a structured warning system for handling various processing issues.
260

261
```python { .api }
262
class MystNBWarnings(Enum):
263
    """
264
    Enumeration of MyST-NB warning types for filtering and error handling.
265
    
266
    Warning types:
267
    - LEXER: Issues with syntax highlighting lexer selection
268
    - FIG_CAPTION: Problems with figure caption processing
269
    - MIME_TYPE: MIME type handling issues  
270
    - OUTPUT_TYPE: Unsupported output type warnings
271
    - CELL_METADATA_KEY: Cell metadata key conflicts
272
    - CELL_CONFIG: Cell-level configuration issues
273
    """
274
    LEXER = "lexer"
275
    FIG_CAPTION = "fig_caption"
276
    MIME_TYPE = "mime_type"
277
    OUTPUT_TYPE = "output_type"
278
    CELL_METADATA_KEY = "cell_metadata_key"
279
    CELL_CONFIG = "cell_config"
280
```
281

282
### Warning Filtering
283

284
```python
285
# In Sphinx conf.py - filter specific warning types
286
import warnings
287
from myst_nb.warnings_ import MystNBWarnings
288

289
# Suppress specific warning types
290
warnings.filterwarnings("ignore", category=UserWarning, 
291
                       message=f".*{MystNBWarnings.LEXER.value}.*")
292
```
293

294
## Custom Lexers
295

296
MyST-NB provides custom Pygments lexers for enhanced syntax highlighting.
297

298
### ANSI Color Lexer
299

300
```python { .api }
301
class AnsiColorLexer:
302
    """
303
    Pygments lexer for ANSI color escape sequences.
304
    
305
    Entry point: 'myst-ansi'
306
    Used for: render_text_lexer configuration
307
    Purpose: Syntax highlighting of terminal output with color codes
308
    """
309
```
310

311
### IPython Traceback Lexer
312

313
```python { .api }
314
class IPythonTracebackLexer:
315
    """
316
    Pygments lexer for IPython/Jupyter error tracebacks.
317
    
318
    Entry point: 'ipythontb'  
319
    Used for: render_error_lexer configuration
320
    Purpose: Enhanced formatting of Python exception tracebacks
321
    """
322
```
323

324
## Important Constants
325

326
### MIME Type Constants
327

328
```python { .api }
329
# Widget-related MIME types
330
WIDGET_STATE_MIMETYPE = "application/vnd.jupyter.widget-state+json"
331
WIDGET_VIEW_MIMETYPE = "application/vnd.jupyter.widget-view+json"
332

333
# Entry point group names
334
RENDER_ENTRY_GROUP = "myst_nb.renderers"
335
MIME_RENDER_ENTRY_GROUP = "myst_nb.mime_renderers"
336

337
# Glue system
338
GLUE_PREFIX = "application/papermill.record/"
339

340
# Sphinx output folder
341
OUTPUT_FOLDER = "jupyter_execute"
342
```