Configuration

MyST-NB can be configured at three levels of specificity; globally, per file, and per notebook cell, with the most specific configuration taking precedence.

Global configuration

Overriding the default configuration at the global level is achieved by specifying variables in the Sphinx conf.py file. All myst_nb configuration variables are prefixed with nb_, e.g.

nb_execution_timeout = 60

Reading

Control how files are read.

Name	Type	Default	Description
nb_custom_formats	Dict[str, Tuple[str, dict, bool]]	{}	Custom formats for reading notebook; suffix -> reader

Execution

This configuration is used to control how Jupyter Notebooks are executed at build-time.

Name	Type	Default	Description
nb_kernel_rgx_aliases	Dict[str, str]	{}	Mapping of kernel name regex to replacement kernel name(applied before execution)
nb_eval_name_regex	str	'^[a-zA-Z_][a-zA-Z0-...	Regex that matches permitted values of eval expressions
nb_execution_mode	Literal['off', 'force', 'auto', 'cache', 'inline']	'auto'	Execution mode for notebooks
nb_execution_cache_path	str	''	Path to folder for caching notebooks (default: )
nb_execution_excludepatterns	Sequence[str]	()	Exclude (POSIX) glob patterns for notebooks
nb_execution_timeout	int	30	Execution timeout (seconds)
nb_execution_in_temp	bool	False	Use temporary folder for the execution current working directory
nb_execution_allow_errors	bool	False	Allow errors during execution
nb_execution_raise_on_error	bool	False	Raise an exception on failed execution, rather than emitting a warning
nb_execution_show_tb	bool	False	Print traceback to stderr on execution error

Rendering

These configuration options affect the look and feel of notebook parsing and output rendering.

Name	Type	Default	Description
nb_merge_streams	bool	False	Merge stdout/stderr execution output streams
nb_render_plugin	str	'default'	The entry point for the execution output render class (in group myst_nb.output_renderer)
nb_remove_code_source	bool	False	Remove code cell source
nb_remove_code_outputs	bool	False	Remove code cell outputs
nb_code_prompt_show	str	'Show code cell {typ...	Prompt to expand hidden code cell {content|source|outputs}
nb_code_prompt_hide	str	'Hide code cell {typ...	Prompt to collapse hidden code cell {content|source|outputs}
nb_number_source_lines	bool	False	Number code cell source lines
nb_mime_priority_overrides	Sequence[Tuple[str, str, Optional[int]]]	()	Overrides for the base render priority of mime types: list of (builder name, mime type, priority)
nb_output_stderr	Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']	'show'	Behaviour for stderr output
nb_render_text_lexer	str	'myst-ansi'	Pygments lexer applied to stdout/stderr and text/plain outputs
nb_render_error_lexer	str	'ipythontb'	Pygments lexer applied to error/traceback outputs
nb_render_image_options	Dict[str, str]	{}	Options for image outputs (class|alt|height|width|scale|align)
nb_render_figure_options	Dict[str, str]	{}	Options for figure outputs (classes|name|caption|caption_before)
nb_render_markdown_format	Literal['commonmark', 'gfm', 'myst']	'commonmark'	The format to use for text/markdown rendering
nb_ipywidgets_js	Dict[str, Dict[str, str]]	{'https://cdnjs.clou...	Javascript to be loaded on pages containing ipywidgets

File level configuration

Overriding the default configuration at a per-file level is achieved by specifying variables in the files metadata, under the mystnb key.

In Jupyter notebooks, this is added in the notebook-level metadata, e.g.

{
  "metadata": {
    "mystnb": {
      "execution_timeout": 60
    }
  }
}

In text-based notebooks, this is added in the YAML top-matter, e.g.

---
file_format: mystnb
mystnb:
  execution_timeout: 60
---

Execution

This configuration is used to control how Jupyter Notebooks are executed at build-time.

Name	Type	Default	Description
eval_name_regex	str	'^[a-zA-Z_][a-zA-Z0-...	Regex that matches permitted values of eval expressions
execution_mode	Literal['off', 'force', 'auto', 'cache', 'inline']	'auto'	Execution mode for notebooks
execution_cache_path	str	''	Path to folder for caching notebooks (default: )
execution_timeout	int	30	Execution timeout (seconds)
execution_in_temp	bool	False	Use temporary folder for the execution current working directory
execution_allow_errors	bool	False	Allow errors during execution
execution_raise_on_error	bool	False	Raise an exception on failed execution, rather than emitting a warning
execution_show_tb	bool	False	Print traceback to stderr on execution error

Rendering

These configuration options affect the look and feel of notebook parsing and output rendering.

Name	Type	Default	Description
merge_streams	bool	False	Merge stdout/stderr execution output streams
render_plugin	str	'default'	The entry point for the execution output render class (in group myst_nb.output_renderer)
remove_code_source	bool	False	Remove code cell source
remove_code_outputs	bool	False	Remove code cell outputs
code_prompt_show	str	'Show code cell {typ...	Prompt to expand hidden code cell {content|source|outputs}
code_prompt_hide	str	'Hide code cell {typ...	Prompt to collapse hidden code cell {content|source|outputs}
number_source_lines	bool	False	Number code cell source lines
mime_priority_overrides	Sequence[Tuple[str, str, Optional[int]]]	()	Overrides for the base render priority of mime types: list of (builder name, mime type, priority)
output_stderr	Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']	'show'	Behaviour for stderr output
render_text_lexer	str	'myst-ansi'	Pygments lexer applied to stdout/stderr and text/plain outputs
render_error_lexer	str	'ipythontb'	Pygments lexer applied to error/traceback outputs
render_image_options	Dict[str, str]	{}	Options for image outputs (class|alt|height|width|scale|align)
render_figure_options	Dict[str, str]	{}	Options for figure outputs (classes|name|caption|caption_before)
render_markdown_format	Literal['commonmark', 'gfm', 'myst']	'commonmark'	The format to use for text/markdown rendering

Cell level configuration

Overriding the default configuration at a per-cell level is achieved by specifying variables in the cell metadata, under the mystnb key.

In Jupyter notebooks, this is added in the cell-level metadata, e.g.

{
  "cell_type": "code",
  "source": ["print('hello world')"],
  "metadata": {
    "mystnb": {
      "number_source_lines": true
    }
  }
}

In text-based notebooks, this is added in the code cell YAML, e.g.

```{code-cell} ipython3
---
mystnb:
  number_source_lines: true
---
print('hello world')
```

Name	Type	Default	Description
merge_streams	bool	False	Merge stdout/stderr execution output streams
remove_code_source	bool	False	Remove code cell source
remove_code_outputs	bool	False	Remove code cell outputs
code_prompt_show	str	'Show code cell {typ...	Prompt to expand hidden code cell {content|source|outputs}
code_prompt_hide	str	'Hide code cell {typ...	Prompt to collapse hidden code cell {content|source|outputs}
number_source_lines	bool	False	Number code cell source lines
output_stderr	Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']	'show'	Behaviour for stderr output
text_lexer	str	'myst-ansi'	Pygments lexer applied to stdout/stderr and text/plain outputs
error_lexer	str	'ipythontb'	Pygments lexer applied to error/traceback outputs
image	Dict[str, str]	{}	Options for image outputs (class|alt|height|width|scale|align)
figure	Dict[str, str]	{}	Options for figure outputs (classes|name|caption|caption_before)
markdown_format	Literal['commonmark', 'gfm', 'myst']	'commonmark'	The format to use for text/markdown rendering

Cell tags

As a convenience for users in Jupyter interfaces, some cell level configuration can be achieved by specifying tags in the cell metadata.

Tags are a list of strings under the tags key in the cell metadata, e.g.

{
  "cell_type": "code",
  "source": ["print('hello world')"],
  "metadata": {
    "tags": ["my-tag1", "my-tag2"],
  }
}

Tag	Description
remove-cell	Remove the cell from the rendered output.
remove-input	Remove the code cell input/source from the rendered output.
remove-output	Remove the code cell output from the rendered output.
remove-stderr	Remove the code cell output stderr from the rendered output.

Additionally, for code execution, these tags are provided (via nbclient):

Tag	Description
skip-execution	Skip this cell, when executing the notebook
raises-exception	Expect the code cell to raise an Exception (and continue execution)

Markdown parsing configuration

The MyST-NB parser derives from the base MyST-Parser, and so all the same configuration options are available. As referenced in MyST configuration options, the full set of global options are:

Name	Type	Default	Description
myst_commonmark_only	bool	False	Use strict CommonMark parser
myst_gfm_only	bool	False	Use strict Github Flavoured Markdown parser
myst_enable_extensions	Set[str]	set()	Enable syntax extensions
myst_disable_syntax	Iterable[str]	[]	Disable Commonmark syntax elements
myst_all_links_external	bool	False	Parse all links as simple hyperlinks
myst_url_schemes	Dict[str, Optional[myst_parser.config.main.UrlSchemeType]]	{'http': None, 'http...	URI schemes that are converted to external links
myst_ref_domains	Optional[Iterable[str]]	None	Sphinx domain names to search in for link references
myst_fence_as_directive	Set[str]	set()	Interpret a code fence as a directive, for certain language names. This can be useful for fences like dot and mermaid, and interoperability with other Markdown renderers.
myst_number_code_blocks	Sequence[str]	[]	Add line numbers to code blocks with these languages
myst_title_to_header	bool	False	Convert a title field in the front-matter to a H1 header
myst_heading_anchors	int	0	Heading level depth to assign HTML anchors
myst_heading_slug_func	Optional[Callable[[str], str]]	None	Function for creating heading anchors, or a python import path e.g. my_package.my_module.my_function
myst_html_meta	Dict[str, str]	{}	HTML meta tags
myst_footnote_transition	bool	True	Place a transition before any footnotes
myst_words_per_minute	int	200	For reading speed calculations
myst_substitutions	Dict[str, Any]	{}	Substitutions mapping
myst_sub_delimiters	Tuple[str, str]	('{', '}')	Substitution delimiters
myst_linkify_fuzzy_links	bool	True	Recognise URLs without schema prefixes
myst_dmath_allow_labels	bool	True	Parse $$...$$ (label)
myst_dmath_allow_space	bool	True	Allow initial/final spaces in $ ... $
myst_dmath_allow_digits	bool	True	Allow initial/final digits 1$ ...$2
myst_dmath_double_inline	bool	False	Parse inline $$ ... $$
myst_update_mathjax	bool	True	Update sphinx.ext.mathjax configuration to ignore $ delimiters
myst_mathjax_classes	str	'tex2jax_process|mat...	MathJax classes to add to math HTML
myst_enable_checkboxes	bool	False	Enable checkboxes
myst_suppress_warnings	Sequence[str]	[]	A list of warning types to suppress warning messages
myst_highlight_code_blocks	bool	True	Syntax highlight code blocks with pygments
myst_inventories	Dict[str, Tuple[str, Optional[str]]]	{}	Mapping of key to (url, inv file), for intra-project referencing

Warning suppression

When Sphinx encounters and error or raises a warning, it will print the location and source file of the text that generated that error. This works slightly differently depending on whether you use markdown files or Jupyter Notebook files.

For markdown (.md) files, Sphinx will correctly report the line number that the error or warning is associated with:

source/path:4: (WARNING/2) Unknown mime type: 'xyz' [mystnb.unknown_mime_type]

For Jupyter Notebook (.ipynb) files, these errors also correspond to a cell index. To allow for this, we use a special format of line number corresponding to: <CELL_INDEX> * 10000 + LINE_NUMBER.

For example, the following error corresponds to Cell 1, line 4:

source/path:10004: (WARNING/2) Unknown mime type: 'xyz' [mystnb.unknown_mime_type]

In general, if your build logs any warnings, you should either fix them or raise an Issue if you think the warning is erroneous. However, in some circumstances if you wish to suppress the warning you can use the Sphinx suppress_warnings configuration option. All myst-nb warnings are prepended by their type, and can be suppressed by e.g.

suppress_warnings = ["mystnb.unknown_mime_type"]