TOC depth on a per-document basis

[mikkvitchko]

Is there a way to limit TOC depth for a specific document?

The toc_depth configuration works for the entire document site, but we struggle with this as many individual documents require their own level for TOC generation.

Is there a way to do this? If not - this would be a much appreciated feature, may be doable with metatags?

[squidfunk]

It’s not possible to achieve this via configuration, but you could just use literal h1-6 tags in your Markdown, as those won’t be included in the table of contents. Note that those headlines will not be targetable via permalinks.

Another idea is to use page-specific CSS and hide the nav levels with display: none. This would leave permalinks intact.

[mikkvitchko]

Thank you! The page-specific CSS idea works for me.

For the benefits of those who may suffer the same pain, here is what I place into my document:

<style>
/*number of ".md-nav__list" determines the max level of TOC to be displayed in TOC*/
/*e.g. if ".md-nav__list" is repeated 2 times - the headers ###, ####, #####,  ... will not be displayed in TOC*/
.md-sidebar--secondary .md-nav__list .md-nav__list {display: none}
</style>

The only issue I have with that is that navigation.tracking is not working properly (obviously, hidden headers are not highlighted, but the upper level header is not highlighted either (if it has some lower level headers).

Is there way to address that?

[squidfunk]

Hmm, good question. I can't really think of a quick hack that solves this problem, because essentially we would have to remove the links from the DOM for a full-working solution. Maybe better to go for the first possibility then.

[ssbarnea]

Not suitable for me because I have a folder with lots of generated md files, and I need to use the custom toc depth for all of them. Adding custom css to 50+ pages does not look as a good idea to me.

Sadly my impression is that the current data model for "nav" does not allow addition of extra properties to apply to pages or sections. If we are to get such inheritable options, the nav structure would have to change to allow that, i guess.

[squidfunk]

You could quite simply craft a custom solution by combining the built-in meta plugin with a block override. You could add a CSS file (or specific overrides) conditionally in the extrahead block, something like:

{% extends "base.html" %}

{% block extrahead %}
  {% if page.meta and page.meta.shallow_toc %}
    <link rel="stylesheet" href="{{ 'stylesheets/shallow_toc.css' | url }}" />
  {% endif %}
{% endblock %}

Now, you could add the shallow_toc: true to the front matter of a page, or to an entire section of your documentation by using the meta plugin as mentioned. The CSS could look like something mentioned in #2532 (reply in thread):

<style>
  .md-sidebar--secondary .md-nav__list .md-nav__list {
    display: none
  }
</style>

Project structure would look like:

.
├─ docs/
│  └─ stylesheets/
│     └─ shallow_toc.css
└─ mkdocs.yml

[Dapsy2000]

Hi all,

I use the first option and hide all headings in the toc from level 4 onwards.
I noticed that the space between two level 3 headings, which have subordinate headings, is not correct.

In my example see the space in the toc between heading Interfaces and Site ID (both ###). Interfaces has additional level 4 headings (####), which I hide.

Another example is the space in the toc between heading Feature and Device Templates.
Feature and Devices Templates are also both Level 3 headings, with Feature Templates having additional Level 4 subheadings.

Here is a screenshot of the toc.

Here is my markdown.

Any idea to fix this?

[squidfunk]

It sounds like this is the same problem as #7978, which is fixed in #7979. Please test the PR, as we're waiting for confirmation by users whether this fixes the issue. Also, please do not hijack unrelated issue or discussions to necropost.