Split docs-content navs in local/preview builds

[bmorelli25]

Summary

Currently, docs-content is being treated as a single content set by docs-builder. While this approach works in many cases, it poses a problem when generating the main TOC. If we generate one combined TOC, it results in over 600+ L1/L2 elements, which is far too many for authors to navigate effectively.

For comparison, the elasticsearch.md sample repo build has about 300 nav elements, and even that feels dense. A single TOC of this size makes it difficult for contributors to effectively add, move, or plan content.

Proposed Solution

To make navigation more manageable for writers working within docs-content, we propose splitting the TOC into smaller, more digestible chunks. Specifically:

1. Split the TOC at the top level: Break the content into multiple TOCs corresponding to individual content sets or categories.
2. Add a selection mechanism: Provide writers with a way to toggle between these TOCs in the local/preview builds, such as:
   • Selectable tabs across the top: Each tab represents a distinct content set or category.
   • A drop-down above the nav: Allows users to choose which content set they want to view.

Why

• A smaller, focused TOC will help authors navigate content more efficiently and reduce cognitive overload.
• Breaking the TOC into distinct chunks will allow writers to focus on specific content sets, making it easier to move, organize, and plan content updates.

Next Steps

1. Evaluate the feasibility of splitting TOCs in docs-content builds without impacting other content sets.
2. Decide what the TOC selection mechanism is.
3. Implement the split TOCs functionality in local/preview builds for testing and feedback.

cc @reakaleek

[Mpdreamz]

We should not be expanding all L1 and L2 navigation items just like the old docs. That already makes our content much more navigatable:

That way even for docs-content the initial navigation would be:

breaking the docset.yml toc could be done today for elasticsearch.md as well.

So each top level folder will define its own toc through toc.yml file.

Most writers will typically start

docs-builder serve

at the start of the day, browse to the L1 they are working on and they can change

L1\toc.yml

and all the files below it and rely on livereload to not have to renavigate constantly to the page they are working on.

If we build anything more special I feel we are hiding a navigation / logical grouping smell that our customers would experience.

[bmorelli25]

That way even for docs-content the initial navigation would be:

That sounds fine for migration. I'm not convinced it's the right play longer-term, but we can cross that bridge later

[reakaleek]

Since collapsing the navigation was a very quick change and suitable for migration this was added in #371