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_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, Union[int, NoneType]]]

()

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

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, Union[int, NoneType]]]

()

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

Sequence[str]

[]

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

Union[Iterable[str], NoneType]

('http', 'https', 'm...

URL scheme prefixes identified as external links

myst_ref_domains

Union[Iterable[str], NoneType]

None

Sphinx domain names to search in for link references

myst_highlight_code_blocks

bool

True

Syntax highlight code blocks with pygments

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 top-matter to a H1 header

myst_heading_anchors

Union[int, NoneType]

None

Heading level depth to assign HTML anchors

myst_heading_slug_func

Union[Callable[[str], str], NoneType]

None

Function for creating heading anchors

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, Union[str, int, float]]

{}

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

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"]