configuration.md

(config/intro)=

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.

:sphinx:
:section: read

Execution

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

:sphinx:
:section: execute

Rendering

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

:sphinx:
:section: render

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.

:sphinx:
:section: execute

Rendering

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

:sphinx:
:section: render

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')
```

:sphinx:

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 {ref}the base MyST-Parser <myst:intro/get-started>, and so all the same configuration options are available. As referenced in {ref}MyST configuration options <myst:sphinx/config-options>, the full set of global options are:

:sphinx:

(myst/error-reporting)=

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