This page was generated from doc/subdir/toctree.ipynb. Interactive online version: . Download notebook.

# 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 further `toctree` directives).

With `nbsphinx` it is possible to get a similar effect within a Jupyter notebook using the `nbsphinx-toctree` cell tag or cell metadata. Markdown cells with `nbsphinx-toctree` tag/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 selected cell, it is used as `toctree` caption (but it also works without a title).

Note

All other content of such a cell is ignored!

If you are satisfied with the default settings, you can simply use `nbsphinx-toctree` as a cell tag.

Alternatively, you can store `nbsphinx-toctree` cell metadata. 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

In 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` 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 (which also will only be visible in the HTML output).

A sub-toctree

- A Notebook that's just a "toctree" Target
- An External Link (HTML only)