Nested toctree links misplaced between left and right menus/navbars

[abravalheri]

Hello @pradyunsg, other maintainers/contributors and Furo's community members. First of all, thank you very much for the awesome theme.

Recently I have been facing some trouble with the way Furo decides to split the TOC between the left and the right navbars/menus. I wonder if that could be an issue.

This is a description of what is happening with a few images to illustrate:

• In a nested page (not index.rst), I have a toctree directive that is being used to tell Sphinx to build extra .rst files containing examples (these files are basic wrappers for a literalinclude directive that points to files outside the docs dir) and link them to the current page. Please notice that this toctree is just used locally inside a subsection of the document, after an h2.

• In the RTD theme, the navbar is rendered as expected: the links in the toctree appear as children of the preceding h2 in the page, as you can see here:

  

• However, since Furo omits nested titles on the left navbar in favour of the menu on the right navbar, something very weird happen: the preceding h2 ends up being shown on the right navbar, while the links in the toctree are displayed on the left navbar right under the h1. As a result the left navbar is confusing because the h1 and the toctree links are not directly related. (You can see it here)

  

---

The .rst file for the page can be found in the PyScaffold repo, and is more or less:

.. docs/extensions.rst

...

Examples
========

Some options for the ``putup`` command are already implemented as extensions
and can be used as reference implementation:

.. toctree::
   :maxdepth: 2

   no-skeleton <examples/no-skeleton-extension>
   no-tox <examples/no-tox-extension>
   cirrus <examples/cirrus-extension>
   gitlab <examples/gitlab-ci-extension>

   namespace <examples/namespace-extension>
   pre-commit <examples/pre-commit-extension>

...

The docs/extnesions.rst file itself is included via the top-level toctree in the index.rst file:

.. docs/index.rst

...

Contents
--------

.. toctree::
   :maxdepth: 2

   Why PyScaffold? <reasons>
   Features <features>
   Installation <install>
   Usage & Examples <usage>
   Advanced Usage & Features <advanced>
   FAQ <faq>
   Contributions & Help <contributing>
   Contributors <contributors>
   Changelog <changelog>
   License <license>
   Module Reference <api/modules>

...

---

Does anyone know a way around this problem? (Or at least omit the nested links on the toctree to show up on the left navbar?)

[pradyunsg]

Separating "in-page content" from "site structure" is an intentional design choice in Furo. What you're doing is adding pages to the site, which is presented in the left sidebar. The right sidebar presents content on the page, which is the headings of the page.

I don't believe there's any way to work around this, since Furo explicitly includes all pages in the site sidebar without any user facing knobs (that was an intentional choice as well, to make it easier to maintain and use).

The only option that I can think of is restructuring the documentation to more clearly reflect the fact that those are examples, by putting the examples toctree under an "Examples" page.

[abravalheri]

Thank you very much for the suggested workaround @pradyunsg .

Just a question: is there any way of hiding a sub-toctree from showing in the left-hand side menu, but still keeping the links in the text body of the page?

[pradyunsg]

No, there isn’t any way to do that.

[abravalheri]

Thank you @pradyunsg

[pradyunsg]

Hello from the future! You can have a :orphan: page, which would be outside of the toctree and thus wouldn't be presented in the sidebar!

See https://github.com/pypa/pip/blob/main/docs/html/reference/pip_download.rst and friends for an example!