Format code cells#

Code cell rendering behaviour is controlled with configuration at a global, per-file, or per-cell level, as outlined in the configuration section.

See the sections below for a description of these configuration option and their effect.

Number source lines#

You can control whether the number of source lines is displayed for code cells, globally with nb_number_source_lines = True, per-file with number_source_lines in the notebook metadata, or per-cell with number_source_lines in the cell metadata. For example:

```{code-cell} ipython3
---
mystnb:
  number_source_lines: true
---
a = 1
b = 2
c = 1
```
1a = 1
2b = 2
3c = 1

stdout and stderr outputs#

Remove stdout or stderr#

In some cases you may not wish to display stdout/stderr outputs in your final documentation, for example, if they are only for debugging purposes.

You can tell MyST-NB to remove these outputs, per cell, using the remove-stdout and remove-stderr cell tags, like so:

```{code-cell} ipython3
:tags: [remove-input,remove-stdout,remove-stderr]

import pandas, sys
print("this is some stdout")
print("this is some stderr", file=sys.stderr)
# but what I really want to show is:
pandas.DataFrame({"column 1": [1, 2, 3]})
```
column 1
0 1
1 2
2 3

Alternatively, you can configure how stdout is dealt with at a global configuration level, using the nb_output_stderr configuration value. This can be set to:

  • "show" (default): show all stderr (unless a remove-stderr tag is present)

  • "remove": remove all stderr

  • "remove-warn": remove all stderr, but log a warning to sphinx if any found

  • "warn", "error" or "severe": log to sphinx, at a certain level, if any found.

Group into single streams#

Cells may print multiple things to stdout and stderr. For example, if a cell prints status updates throughout its execution, each of these is often printed to stdout. By default, these outputs may be split across multiple items, and will be rendered as separate “chunks” in your built documentation.

If you’d like each of the outputs in stderr and stdout to be merged into a single stream for each, use the following configuration:

nb_merge_streams = True

This will ensure that all stderr and stdout outputs are merged into a single group. This also makes cell outputs more deterministic. Normally, slight differences in timing may result in different orders of stderr and stdout in the cell output, while this setting will sort them properly.

Outputs MIME priority#

When Jupyter executes a code cell it can produce multiple outputs, and each of these outputs can contain multiple MIME media types, for use by different output formats (like HTML or LaTeX).

MyST-NB stores a base priority dictionary for most of the common Sphinx builder names, mapping MIME types to a priority number (lower is higher priority):

import yaml
from myst_nb.core.render import base_render_priority
print(yaml.dump(base_render_priority()))
applehelp:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 50
  image/jp2: 80
  image/jpeg: 60
  image/png: 40
  image/svg+xml: 90
  image/tiff: 70
  text/html: 30
  text/latex: 110
  text/markdown: 100
  text/plain: 120
changes:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
devhelp:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 50
  image/jpeg: 60
  image/png: 40
  text/html: 30
  text/latex: 80
  text/markdown: 70
  text/plain: 90
dirhtml:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
dummy:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
epub:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
gettext:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
html:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
htmlhelp:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 50
  image/jpeg: 60
  image/png: 40
  text/html: 30
  text/latex: 80
  text/markdown: 70
  text/plain: 90
json:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
latex:
  application/pdf: 10
  image/jpeg: 30
  image/png: 20
  text/latex: 40
  text/markdown: 50
  text/plain: 60
linkcheck:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
man:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
pickle:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
pseudoxml:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
qthelp:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
readthedocs:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
readthedocsdirhtml:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
readthedocssinglehtml:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
readthedocssinglehtmllocalmedia:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
singlehtml:
  application/javascript: 20
  application/vnd.jupyter.widget-view+json: 10
  image/gif: 60
  image/jpeg: 70
  image/png: 50
  image/svg+xml: 40
  text/html: 30
  text/latex: 90
  text/markdown: 80
  text/plain: 100
texinfo:
  image/gif: 30
  image/jpeg: 20
  image/png: 10
  text/latex: 40
  text/markdown: 50
  text/plain: 60
text:
  text/latex: 10
  text/markdown: 20
  text/plain: 30
xml:
  text/latex: 10
  text/markdown: 20
  text/plain: 30

Items in this dictionary can be overridden by the nb_mime_priority_overrides configuration option, in your conf.py. For example, the following configuration applies in order:

  • Sets text/plain as the highest priority for html output.

  • Disables image/jpeg for latex output

  • Adds a custom MIME type customtype for all builders (* applies to all builders)

nb_mime_priority_overrides = [
  ('html', 'text/plain', 0),
  ('latex', 'image/jpeg', None),
  ('*', 'customtype', 20)
]

Changed in version 0.14.0: nb_mime_priority_overrides replaces nb_render_priority

See also

Customise the render process, for a more advanced means of customisation.

Images and Figures#

With the default renderer, for any image types output by the code, we can apply formatting via cell metadata. The top-level metadata key can be set using nb_cell_metadata_key in your conf.py, and is set to mystnb by default. Then for the image we can apply all the variables of the standard image directive:

  • width: length or percentage (%) of the current line width

  • height: length

  • scale: integer percentage (the “%” symbol is optional)

  • align: “top”, “middle”, “bottom”, “left”, “center”, or “right”

  • classes: space separated strings

  • alt: string

Units of length are: ‘em’, ‘ex’, ‘px’, ‘in’, ‘cm’, ‘mm’, ‘pt’, ‘pc’

You can also wrap the output in a figure, that can include:

  • align: “left”, “center”, or “right”

  • caption: a string, which must contain a single paragraph and is rendered as MyST Markdown (subsequent paragraphs are added as a legend)

  • caption_before: a boolean, if true, the caption is rendered before the figure (default is false)

  • name: by which to reference the figure

  • classes: space separated strings

```{code-cell} ipython3
---
mystnb:
  image:
    width: 200px
    alt: fun-fish
    classes: shadow bg-primary
  figure:
    caption: |
      Hey everyone its **party** time!

      (and I'm a legend)
    name: fun-fish-ref
---
from IPython.display import Image
Image("images/fun-fish.png")
```
from IPython.display import Image
Image("images/fun-fish.png")
fun-fish

Hey everyone its party time!#

(and I’m a legend)

Now we can link to the image from anywhere in our documentation: swim to the fish

You can create figures for any mime outputs, including tables:

```{code-cell} ipython3
---
mystnb:
  figure:
    align: center
    caption_before: true
    caption: This is my table caption, above the table
---
import pandas
df = pandas.DataFrame({"column 1": [1, 2, 3]})
df = df.style.set_table_attributes('class="dataframe align-center"')
df
```
import pandas
df = pandas.DataFrame({"column 1": [1, 2, 3]})
df = df.style.set_table_attributes('class="dataframe align-center"')
df

This is my table caption, above the table#

  column 1
0 1
1 2
2 3

Markdown#

The format of output text/markdown can be specified by render_markdown_format configuration:

CommonMark formatting will output basic Markdown syntax:

from IPython.display import display, Markdown
display(Markdown('**_some_ markdown** and an [a reference](https://example.com)!'))

some markdown and an a reference!

and even internal images can be rendered!

display(Markdown('![figure](../_static/logo-wide.svg)'))

figure

But setting the Markdown format to myst will allow for more advanced formatting, such as including internal references, tables, and even other directives, either using:

  • myst_render_markdown_format = "myst" in the conf.py to set globally, or

  • markdown_format in the cell metadata to set per-cell.

````{code-cell} ipython3
---
mystnb:
  markdown_format: myst
---
display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))
display(Markdown("""
| a | b | c |
|---|---|---|
| 1 | 2 | 3 |
"""))
display(Markdown("""
```{note}
A note admonition!
```
"""))
````

The parsed Markdown is integrated into the wider documentation, and so it is possible, for example, to include internal references:

display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))
display(Markdown("""
| a | b | c |
|---|---|---|
| 1 | 2 | 3 |
"""))
display(Markdown("""
```{note}
A note admonition!
```
"""))

some markdown and an internal reference!

a

b

c

1

2

3

Note

A note admonition!

ANSI Outputs#

By default, the standard output/error streams and text/plain MIME outputs may contain ANSI escape sequences to change the text and background colors.

import sys
print("BEWARE: \x1b[1;33;41mugly colors\x1b[m!", file=sys.stderr)
print("AB\x1b[43mCD\x1b[35mEF\x1b[1mGH\x1b[4mIJ\x1b[7m"
      "KL\x1b[49mMN\x1b[39mOP\x1b[22mQR\x1b[24mST\x1b[27mUV")
ABCDEFGHIJKLMNOPQRSTUV
BEWARE: ugly colors!

This uses the built-in AnsiColorLexer pygments lexer. You can change the lexer used in the conf.py, for example to turn off lexing:

nb_render_text_lexer = "none"

The following code1 shows the 8 basic ANSI colors it is based on. Each of the 8 colors has an “intense” variation, which is used for bold text.

text = " XYZ "
formatstring = "\x1b[{}m" + text + "\x1b[m"

print(
    " " * 6
    + " " * len(text)
    + "".join("{:^{}}".format(bg, len(text)) for bg in range(40, 48))
)
for fg in range(30, 38):
    for bold in False, True:
        fg_code = ("1;" if bold else "") + str(fg)
        print(
            " {:>4} ".format(fg_code)
            + formatstring.format(fg_code)
            + "".join(
                formatstring.format(fg_code + ";" + str(bg)) for bg in range(40, 48)
            )
        )
            40   41   42   43   44   45   46   47  
   30  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;30  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   31  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;31  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   32  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;32  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   33  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;33  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   34  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;34  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   35  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;35  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   36  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;36  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   37  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;37  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 

Note

ANSI also supports a set of 256 indexed colors. This is currently not supported, but we hope to introduce it at a later date (raise an issue on the repository if you require it!).

Customise the render process#

The render process is governed by subclasses of NbElementRenderer, which dictate how to create the docutils AST nodes for elements of the notebook.

Implementations are loaded via Python entry points, in the myst_nb.renderers group. So it is possible to inject your own subclass to fully override rendering.

For example, the renderer loaded in this package is:

[project.entry-points."myst_nb.renderers"]
default = "myst_nb.core.render:NbElementRenderer"

You can then select the renderer plugin in your conf.py:

nb_render_plugin = "default"

Plugins can also override rendering of particular output MIME types, using the myst_nb.mime_renderers entry point group to supply functions with signature: MimeRenderPlugin.

For example myst_nb.core.render.ExampleMimeRenderPlugin, is loaded in this package:

[project.entry-points."myst_nb.mime_renderers"]
example = "myst_nb.core.render:ExampleMimeRenderPlugin"

Meaning we can now render custommimetype in all output formats:

from IPython.display import display
display({"custommimetype": "Some text"}, raw=True)

This is a custom mime type, with content: ‘Some text’


1

Borrowed from nbsphinx!