Show TOC from root index.html on left sidebar

[jrbourbeau]

I'd like to show the TOC for the root page (index.html) on the left sidebar and was wondering if it's currently possible to do so. Today the sphinx TOC appears on the left sidebar for index.html pages that are in subdirectories, but not the root index.html page.

├── index.rst        <-- TOC not in left sidebar
└── inner_section
    ├── index.rst    <--- TOC is in left sidebar
    ├── ...
    └── ...

As an example, see the pydata-sphinx-theme documentation page:

• pydata-sphinx-theme root (index.html)
• pydata-sphinx-theme user guide page (user_guide/index.html)

[choldgraf]

just to clarify - do you mean in addition to the links at the top, or instead of the links at the top?

[jrbourbeau]

In addition to the links at the top. I was envisioning a more detailed TOC on the left sidebar, e.g. :maxdepth: 2, but still having the links at the top like all the other pages.

[jorisvandenbossche]

Today the sphinx TOC appears on the left sidebar for index.html pages that are in subdirectories, but not the root index.html page.

That is because for the root index.html, this TOC is actually already shown, but in the header.

This theme basically tries to look at the global toctree of the full sphinx site, and the puts the first level in the top header bar, and the second (+ potentially third) level in the left sidebar.

There are variants possible where all levels of navigation are put in the left sidebar, see eg #90

[jorisvandenbossche]

In addition to the links at the top. I was envisioning a more detailed TOC on the left sidebar, e.g. :maxdepth: 2, but still having the links at the top like all the other pages.

But so for the root index.html, which more detailed TOC are you thinking of?
Eg for https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html, there is no more detailed TOC for the home page. There is only a more detailed TOC if you choose one of the top-level pages (on the root index.html, none of the first-level navigation items are active, so we can't choose which second-level navigation items to show)

A more concrete example would probably help to try to clarify what you mean or want to achieve.

[choldgraf]

I think it could be beneficial to have top-level links there only for the landing page, just to avoid having that kinda awkward white-space?

Note that this will be quite easy to special-case for the master_doc page if #219 lands.

[jorisvandenbossche]

I think it could be beneficial to have top-level links there only for the landing page

But which top-level links? Repeat the ones of the header bar?
That is a possibility, but might also give a strange duplication?

To be clear, I fully agree the home page right now is not looking good with the empty side bar, but I think a more custom design might be the better solution (-> #146)

[choldgraf]

Repeat the ones of the header bar?

yeah that's what I had in mind. I agree it'd be a bit weird to duplicate them though

[jpmckinney]

I don't think it makes sense to repeat navigation.

To fill the space, users might want to configure html_sidebars to display some homepage-specific content instead (e.g. the organization behind the project, sponsors, community links, whatever).

Alternately, the homepage might be fuller width.

[choldgraf]

@jpmckinney agreed - I think this issue came up before the html_sidebars was supported, but now that it is perhaps this is less of an issue. @jrbourbeau what do you think?

[jonnew]

I would like to have a left side bar on the top level page to show other top level pages that are not master_doc/index.html. For instance, I have a FAQ and contact pages. Making an entire top-level "About" entry in the nav-bar for those two pages feels kinda strange. I would rather have the ability to link them in the side bar of the main page. Although, this might be a different issue as I don't want to repeat what is in the top bar on the side.

[drammock]

@jonnew have a look at what MNE-Python does: the html_sidebars configuration (here) lets us specify a couple items (the custom one is here) that only show up on the homepage's left sidebar; other pages get the default TOC in the left sidebar.

[jonnew]

@drammock That's exactly right. Thank you!

[maximlt]

Looks like we've managed to achieve what the OP wanted on one of our websites (https://holoviews.org/index.html).

And when I see it in action I think it's a better default than the empty sidebar. It also allows to get to a specific page more quickly (by expanding an item).

I would actually like to replicate that on each one of our sites, the problem is that I really have no clue how the TOC ended up being displayed in the sidebar on this site 🙃

[choldgraf]

I just realized that doing this would be very simple, so gave it a quick shot in #536

[damianavila]

Interesting related comment from another issue: #536 (comment)

[choldgraf]

Just a note that if our main concern is that landing pages of sites look "wrong" because of all the whitespace to the left, another approach is that we could remove the left sidebar entirely on landing pages. The main problem with this is that the search bar defaults to the left. However, we could change the default to be in the navbar instead of the left sidebar. In this case, if there were no sidebar items to display, then the sidebar would disappear entirely and the content would center.

There is a good amount of precedence for this. For example, the following topbar-based themes have their search in the topbar by default:

Docasaurus:

Material mkdocs:

GitBook:

[damianavila]

Another interesting comment from @jbednar: #536 (comment)

[damianavila]

There is a good amount of precedence for this. For example, the following topbar-based themes have their search in the topbar by default:

I was going to suggest the same... It is always "weird" to me to not see the search box in the navbar and that is maybe because that pattern is pretty well extended and predominant by now.

[maximlt]

+1 for having the search box in the navbar, like in the examples shown above and like on Facebook or Linkedin.

[jorisvandenbossche]

Yes, I think that indeed moving the search box might make sense.

Exploring some more sites:

The original layout if this theme was based on the bootstrap docs site, as you can see here (https://getbootstrap.com/docs/4.1/getting-started/introduction/):

However, in their latest version, they actually also moved the search box ((https://getbootstrap.com/docs/5.1/getting-started/introduction/):

It is now in the second navbar (when scrolling down, it's only this second navbar that stays visible):

Other documentation sites I often check for inspiration, and also have it in the top navbar, are Docker (https://docs.docker.com/get-started/):

and Tensorflow (https://www.tensorflow.org/tutorials):

One other example of a documentation framework with the search box in the sidebar is Docsy (https://www.docsy.dev/docs/examples/):

But here the search box stays on top and only the navigation tree scrolls (xref #560):

[dstansby]

Another reason to have the sidebar on the index page is on readthedocs - the sidebar needs to be present to show the version switcher, so by default the readthedocs version switcher isn't currently shown on the root page 😢

[robmoss]

Another reason to have the sidebar on the index page is on readthedocs - the sidebar needs to be present to show the version switcher, so by default the readthedocs version switcher isn't currently shown on the root page 😢

This is my one and only use case for this feature.

Edit: I've made a custom template based on toctree.html, where I pass startdepth=0 and maxdepth=1, and add it to the 'index' entry in the html_sidebars dictionary. My one reservation is keeping this template consistent with future versions of the pydata-sphinx theme.

[drammock]

I think this can be closed now:

• since Stop moving the Read the Docs version switcher into the sidebar #2034 the RTD switcher is no longer forced into the left sidebar.
• since even longer ago, the search bar is in the top navbar by default (not left sidebar).
• issues with the "unbalanced look" of homepages can be addressed by suppressing the left sidebar on specific pages; guidance is in https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#remove-the-primary-sidebar-from-pages

[maximlt]

@drammock how does one display the TOC on the root index in the left sidebar with the latest version of the theme?

[drammock]

@drammock how does one display the TOC on the root index in the left sidebar with the latest version of the theme?

I would consider that wontfix, or at least very low priority to add/support.
Adding layout variants w/r/t the TOC has been discussed elsewhere (as mentioned near the start of this thread), and although we recognize it would be great to offer, so far none of the maintainers have said "let's go for it", I think because:

1. it's a big lift in terms of added complexity, which has long-term maintenance/support commitments that nobody on the maintainer team is comfortable with yet, because
2. there are lots of other fixes/enhancements that are higher priority for us (especially w/r/t accessibility), and
3. there are some really nice alternative themes that are designed with the root TOC in the left sidebar (sphinx book theme and furo are the top two that we recommend, e.g. here)

[maximlt]

Ok thanks for the answer. I still think that'd be a useful feature, I use it quite a lot when going on a website and expanding the items in the side bar to go directly to the documentation page I'm after.

For reference, we're replacing the default sidebar template with this one to obtain this behavior:

<!-- Adapted from sidebar-nav-bs.html (1.15.2) with the following changes

  - Commented out the tag that adds the "Section Navigation" title
  - Call generate_toctree_html with startdepth=0

Please update this file when required when bumping the max pin of pydata-sphinx-theme.
-->

{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #}
<nav class="bd-docs-nav bd-links"
      aria-label="{{ _('Section Navigation') }}">
  <!-- <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p> -->
  <div class="bd-toc-item navbar-nav">
    {{- generate_toctree_html(
      "sidebar",
      startdepth=0,
      show_nav_level=theme_show_nav_level | int,
      maxdepth=theme_navigation_depth | int,
      collapse=theme_collapse_navigation | tobool,
      includehidden=theme_sidebar_includehidden | tobool,
      titles_only=True
      )
    -}}
  </div>
</nav>