Using `toctree` In A Notebook¶

In Sphinx-based documentation, there is typically a file called index.rst which contains one or more toctree directives. Those can be used to pull in further source files (which themselves can contain toctree directives).

With nbsphinx it is possible to get a similar effect within a Jupyter notebook using the "nbsphinx-toctree" cell metadata. Markdown cells with "nbsphinx-toctree" metadata are not converted like “normal” Markdown cells. Instead, they are only scanned for links to other notebooks (or *.rst files and other Sphinx source files) and those links are added to a toctree directive. External links can also be used, but they will not be visible in the LaTeX output.

If there is a section title in the cell, it is used as toctree caption (but it also works without a title).

Note:

All other content of such a cell is ignored!

Use ...

"nbsphinx-toctree": {}

... for the default settings, ...

"nbsphinx-toctree": {
  "maxdepth": 2
}

... for setting the :maxdepth: option, or...

"nbsphinx-toctree": {
  "hidden": true
}

... for setting the :hidden: option.

Of course, multiple options can be used at the same time, e.g.

"nbsphinx-toctree": {
  "maxdepth": 3,
  "numbered": true
}

For more options, have a look a the Sphinx documentation. All options can be used – except :glob:, which can only be used in rst files and in raw reST cells.

Note that in the HTML output, a toctree cell generates an in-line table of contents (containing links) at its position in the notebook, whereas in the LaTeX output, a new (sub-)section with the actual content is inserted at its position. All content below the toctree cell will appear after the table of contents/inserted section, respectively. If you want to use the LaTeX output, it is recommended that you don’t add further cells below a toctree cell, otherwise their content may appear at unexpected places. Multiple toctree cells in a row should be fine, though.

The following cell is tagged with "nbsphinx-toctree" metadata and contains a link to the notebook yet-another.ipynb and an external link (which will only be visible in the HTML output). It also contains a section title which will be used as toctree caption.

A sub-toctree

Using toctree In A Notebook¶

Using `toctree` In A Notebook¶