mkdocs - How can I specify toc_depth for a single document?

Question

I want to change the depth of the number of headers the table of contents present on the TOC.

I can see toc_depth option exists as a configuration option but this is global. Is there a way to specify a single document?

Cheers

Answer 1

You can update your templates using custom templates. Override the toc.html template file item macro https://github.com/mkdocs/mkdocs/blob/234fb10e543af4c5dcf0ee54c1d831846303f4cb/mkdocs/themes/mkdocs/toc.html#L9 and replace:

{%- if item.level <= config.theme.navigation_depth %}

by something like:

{% if not page.meta.toc_depth or item.level <= page.meta.toc_depth or item.level <= config.theme.navigation_depth %}

and add toc_depth in meta header of your .md page.

---
description: this is the page I want TOC to only display level 2 max.
toc_depth: 2
---

If you use Material for MkDocs theme you can override the partials/toc-item.html file with the following:

{% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %}