Front page sidebar consistently empty

[vsoch]

Hiya! I'm really liking how it looks when the sidebar is single on the left, but for the life of me I can't get any content to ever show in the sidebar on the first page! E.g.,:

For another project I did a hack to select the sidebar and add an image so it doesn't look so offset and empty: https://flux-framework.org/flux-operator/

But what I'd really like here is something akin to how it looks on the other pages, e.g.,

Thank you - I really appreciate the help! I stumbled on the template looking for more features from sphinx material and (aside from this tiny issue) am really loving it.

[jbms]

When you use the navigation.tabs feature the top level of the TOC is displayed as tabs, and the left sidebar shows only the TOC headings under the current selected tab. With the Sphinx document model, there is always a master document that is at the root of the TOC, and therefore for the master document there is no selected tab.

I guess there are two possible solutions:

1. On the master document, populate the left-side TOC with the headings from one of the tabs, such as the first tab, even though that tab is not selected. This might sometimes work okay, though it may also be confusing.

2. Change the Sphinx document model a bit, e.g.

   • The master document (e.g. named "toc") would define the TOC but would not contain any content, and would not be generated as an HTML page.
   • Instead, you would use a different document (which could still be named "index") as the "home page", such as the "quickstart" page shown in your screenshot.
   • Some minor changes could be made to ensure that nothing in the header links to the missing master document.

[vsoch]

I would be open to any solution, and actually since you develop this I think I'd err on wanting to go with what you think is best. Can you tell me why to try/do (e.g., I probably need references to your docs for how to do each of those bullets - I'm new to the template!)? :thinking:

[jbms]

To be clear both of those solutions would require implementation work (which might fall to you if you want it to happen). I was just throwing out some possibilities.

If this is just an aesthetic consideration, you might consider other ways of restructuring your home page to make it less empty. If you have sections within the home page there will be a right TOC, for example.

[vsoch]

Yeah! I was able to see the right TOC - but it's still jarringly empty on the left. The hack I am using for my other project is to add content there with Javascript, which isn't ideal. Could there be some way to have custom logic in _templates just for the index page?

[2bndy5]

Yeah, easiest solution would be to add subheadings to the root doc. Maybe a "who we are" or "[soft/hard] requirements" sections are applicable to add to a docs' root page.

Coding a solution would be difficult for newcomers (peek at sphinx_immaterial/nav_adapt.py if you're feeling brave). The HTML templates are not to be altered with non-trivial modifications (see our contributing guidelines).

[vsoch]

Apologies for the stupid question - but could you clarify what you mean by subheading? The index.rst has these levels already:

Welcome to Flux's documentation!
================================

<content>

Subheading(?)
-------------

[2bndy5]

Yes that would be a subheading.

You can also remove the left empty toc entirely by using the metadata key :hide-navigation: which only effects the page in which the metadata key was found (usually at the top of the doc's src).

:hide-navigation:

Welcome to Flux's documentation!
================================

<content>

Subheading
-------------

[vsoch]

Oh :hide-navigation: is perfect! The page is visually centered. I can totally work with this - thanks @2bndy5 ! If you want to leave the issue to come back to the options mentioned above, I can definitely stay involved.

[2bndy5]

If you're happy, then I'm happy; I ❤️ your enthusiasm though

I think this issue amounts to the differences between mkdocs site structure vs sphinx site structure (which is why nav_adapt.py is so complicated). I'm actually going to close this issue as it seems like an edge case (at least the first reported case). If we need to address it in the future, then I'm inclined to add documentation (rather than hardcode a specific solution), but I can be swayed otherwise.