Making left sidebar have dropdowns for sub TOCs

[npetersen2]

Hi, I am trying to replicate the sidebar on the main furo website:

Where the sidebar is collapsed by default and you can open it up to browse the sub-pages. Very nice.

However, I cannot figure out how to do this on my site...

• I have a top level page: firmware/arch/index
• With three children: firmware/arch/subpage1, firmware/arch/subpage2, firmware/arch/subpage3

In my main TOC in my top level, I link ONLY to firmware/arch/index. Then, inside of firmware/arch/index, I create a TOC for the sub pages. Both TOC are marked as hidden.

However, when the site renders, the subpages are not in a drop down! They are just shown at the same level as the firmware/arch/index page.

How do I get them to appear as children of the top page?

[pradyunsg]

Getting the sidebar to behave like this (with dropdowns, and dealing with complexity of having a collapse button) is... non-trivial with Sphinx. You can get indentation by having a margin-left set only on nested uls.

https://github.com/pradyunsg/furo/blob/0c4018fa730d12dc2144745b75c33b922b7cf7d4/src/furo/navigation.py has most of the HTML adaptation necessary, to get things to work correctly.

https://github.com/pradyunsg/furo/blob/0c4018fa730d12dc2144745b75c33b922b7cf7d4/src/furo/assets/styles/components/_sidebar.sass has the relevant stylesheet, for getting the sidebar to look right.

[npetersen2]

Thanks, @pradyunsg for the reply!!

I am a bit new to Sphinx and theming. Are the files you linked already in the furo theme I have installed? as in, I do not need to do anything and the sidebar should be able to behave like the main furo site? Or, do I need to alter something to get my installed furo theme to work like the example site?

[pradyunsg]

Ah, I think I misunderstood what you were asking.

[pradyunsg]

Are you trying to get sidebar dropdowns in a Furo-based documentation site?

Here's a small example of how to do that:

index.rst

Home
====

.. toctree::
   page
   dropdown/index

page.rst

Page
====

dropdown/index.rst

Dropdown
========

.. toctree::
   inner

dropdown/inner.rst

Inner
====

conf.py

html_theme = "furo"

This will generate:

[npetersen2]

@pradyunsg thanks for the example.

After a lot of playing, I finally figured out why mine wasn't working. I think this is a bug somewhere.

To reproduce: Simply swap the ordering of the toctree declaration in the dropdown rst file:

dropdown/index.rst becomes:

.. toctree::
   inner

Dropdown
========

Now, the dropdown doesn't render at all. Everything is just flat in the side bar.

From user side, easy to fix this by always putting the toctree declaration at the bottom of the file.

[pradyunsg]

Looks like a bug in either docutils or sphinx.