Allow users to specify navigation depth for sidebar TOC tree in a clear way

[orhanrauf]

I would like to be able to create dropdowns (to also show contents on pages) in the sidebar navigation through a simple parameter for the html_theme_options or something similar, as currently it is unclear as to how to do this (have been searching for 2 hours now)

[pradyunsg]

See #318 (comment)

[orhanrauf]

Thanks for the reply! I understand this works for directives, but how does this work for contents on a page?

[pradyunsg]

Hmm... Do you have an example of what you're trying to achieve? A screenshot or two might help explain what you want to do, since it's not particularly clear to me what you want to do.

[KasperLin]

If I'm understanding @orhanrauf correctly, what he was asking for is something like show_toc_level in pydata-sphinx-theme, which controls the depth level of the right TOC sidebar, instead of the left NAV sidebar.

That is exactly what I've been looking for desperately in the past few months.

For the right TOC sidebar, being able to show only headers in given depth, and reveal deeper levels automatically on scrolling is super useful, creating a simple and intuitive user experience, allowing more efficient navigation & a clean layout at the same time.

Besides PyData theme, Jupyter Book theme and several others also support it.

I think this feature meets the furo design philosophy pretty well, and is the last thing I ask for for this amazing theme.

@pradyunsg Is such thing technically possible in furo ? Please let us know !

[sscherfke]

I think this is what you need: https://gitlab.com/sscherfke/typed-settings/-/blob/main/docs/apiref.rst?plain=1#L1

Took me a while to figure it out, too.

:tocdepth: 4 on the top of the file

[pradyunsg]

Oh beautiful @sscherfke! ^>^

[pradyunsg]

As @sscherfke has helpfully pointed out, Sphinx supports limiting the depth of the page table of contents (i.e. right sidebar) out of the box, with :tocdepth: metadata in a file.

For reStructuredText source files, you can have the following at the top of your file:

:tocdepth: 5

For Markdown source files (using MyST-parser), you can have the following at the top of your file:

---
tocdepth: 5
---

(pick whatever number you want; I've arbitrarily shown 5)

The relevant section in Sphinx's documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#special-metadata-fields

[KasperLin]

Thanks both of you @sscherfke & @pradyunsg for the great reply ! The tocdepth metadata answers the original question perfectly.

Unfortunately, this only solves part of my issue ....... for I want not only to control "TOC depth", but also "show & hide deeper level automatically when scrolling actively" (like pydata), which I find really helpful & elegant.

Here is a good example of this feature, try scrolling !

I really want to know if furo can support this feature ? Should I open a new discussion for this specific need ?

[pradyunsg]

A new discussion would be better, yea.