tableofcontents directive in document with no descendants [etoc.tableofcontents]

[giswqs]

I am trying to insert a table of contents into a page built from myst using the {tableofcontents} directive, but got a warning saying that tableofcontents directive in document with no descendants [etoc.tableofcontents]. The table of contents does not show up on the HTML page. Any advice?

[choldgraf]

The tableofcontents directive is for listing sub-pages underneath the current page. Is this true in your case? Eg are there files listed under "sections" in your toc.yml file?

[giswqs]

BTW, is it possible to control the max depth of TOC generated using the {contents} directive? For example, I only want the TOC to show heading levels up to 3. The max depth of the {tableofcontents} directive can be specified in the _toc.yml, but the contents directive does not seem to have this option.

[choldgraf]

Yep - two answers below:

To remove the title could you try adding the :local: argument? The :local: argument should only include the contents in the current section, and if you put this under the title, this should be all top-level sections.

To limit the depth could you try adding a :depth: argument? e.g. :depth: 2.

So something like:

# Page title

```{contents}
:local:
:depth: 2
```

[giswqs]

It works like charm. Thanks a lot for helping out.

I think this would be useful to add to the documentation. It will help newcomers.
https://jupyterbook.org/structure/toc.html

[choldgraf]

@giswqs I agree! Would you be willing to add a short PR? I am happy to review and edit as needed!

[giswqs]

Just submitted the PR. Thanks. jupyter-book/jupyter-book#1683