theme: Add site hierarchy to left sidebar

[jmooring]

Using a hierarchical tree on the left is how most documentation sites handle navigation. Options:

1. Two levels (e.g., Reference > Methods)
2. Three levels (e.g., Reference > Methods > Resource)
3. All levels, recursive until we get to the lowest section (e.g., Reference > Methods > Resource > MediaType) . With this approach we would remove the "in this section" block from the right side bar.

It would be nice if the implementation were configurable. For example, number_of_levels = n where n is 1, 2, 3, etc. or -1 for all.

[bep]

Using a hierarchical tree on the left is how most documentation sites handle navigation.

That alone is not a very convincing argument. I suspect my prompt may have lead Claude in a certain direction when I asked "him" to reserch this, but I have pasted it below.

I'm an expert Hugo user, so not typical, but I really like having the article text being the first thing my eyes sees when reading. And I have grown to especially dislike these typical deep navigation trees with these + signs that allows you to navigate to any page by expanding/collapsing nodes. in bigger sites. So, now that we have gotten to a state where the section tree actually means something, I may be convinced to add something like this. But in my head it would be: render all the nodes down to the current (or to the level defined), no magic JavaScript expansion of other nodes, you need to navigate to a new section to expand it.

---

Research on Sidebar Navigation vs. Content-First Design

Key Research Findings:

Information Foraging Theory (Nielsen Norman Group)

The foundational research from PARC shows that users make rational decisions about effort-to-benefit ratio when navigating. Users want to maximize the rate of information gain—getting as much relevant information as possible in minimum time. This means users will skip elements that don't directly contribute to their goal. A cluttered sidebar actually increases cognitive load and time-to-content.

Sidebar Navigation Doesn't Always Help

Multiple peer-reviewed studies show:

• A 2022 study on "Menu design on small display user interfaces" found users can effectively use the search function, alphabetic bar, and information-based navigation as alternatives to breadth-on-navigation menus
• A 2021 study on "Navigation User Interface design in e-commerce" found that different navigation menu styles affected website trust and user behavior
• Studies specifically measuring "behavioral effects of constantly visible site maps" suggest visibility ≠ usability

Search vs. Menu Navigation

Recent A/B testing research shows that users often prefer search when available, especially for specific queries. The fact that you already have breadcrumbs and section listings means you're covering the key discovery mechanisms—search handles specific lookups, breadcrumbs provide context, and section listings show what's available.

Your Existing Strengths:

• Content-first design aligns with information foraging principles
• Breadcrumbs provide context without displacing content
• Search functionality lets users skip to goals directly
• Section listings offer browsable alternatives

Conclusion:

The "everyone does it" argument is actually undermined by research showing that good design optimizes for your specific use case rather than copying patterns blindly. For documentation (where users have clear goals), your current approach is evidence-based.

[jmooring]

That alone is not a very convincing argument

Agreed. I think we need something to improve navigation, but I'm not quite sure what that is.

For reference information (functions/methods/etc) I think what we have is fine... the use case is "random access" to information.

But for a section labeled "tutorials" or "guides", we want to provide "sequential access" to information (e.g., read this, then read this, then read this, etc.). A tree may help with that, or maybe there's a better way. Needs some thought...