Auto generate nav based on pages Headers 2

[ia3andy]

          Maybe there is an Asciidoc macro or something that will generate the TOC based on the file. I know there is this: https://docs.asciidoctor.org/asciidoc/latest/toc/ but it doesn't seem to work for XREF links

Originally posted by @gastaldi in quarkiverse/quarkus-renarde#148 (comment)

[holly-cummins]

Isn't this done already?

See, for example, https://docs.quarkiverse.io/quarkus-pact/dev/consumer-index.html. I did a quick code search, and all the content in the right is only based on headers, not on manual config.

[holly-cummins]

Or is the idea to also have that content on the right appear on the left? I think that's just a layout thing, not a generation thing, but I'd need to experiment.

Maybe @ia3andy you could provide a screenshot of the intended effect? I looked at quarkiverse/quarkus-renarde#148 (comment) but it wasn't clear enough to me where the nav was, and what was different from the current state.

[ia3andy]

@holly-cummins so as a User point of view, it seems to me that:

• Left nav is top level main menu/nav (currently manual)
• Right nav is page deep summary/nav (automatic)

In the left Nav, I would automatically link to all pages and reference h2 (main titles)
In the right Nav, keep it as it is.

[holly-cummins]

Do you think there's value in having stuff over in the right that duplicates stuff on the left? It feels like ... a lot of duplication.

I know it's how Antora pages are usually structured, but that doesn't make it good. :) I wonder if just having everything on the left would be more natural to people who weren't antora-users.

On the left nav, automatically discovering the pages may need some thought, to make sure we

• don't break existing navs
• do the right thing

We can apply a convention that index.adoc is the top level, but if there's multiple other adocs, we may need to do something clever to order them. I guess requiring the adoc pages to be numbered would sort it out.

I also don't know if antora lets us drop the nav element in antora.yml, but I can do some experiments.

I agree that when viewing an extension, the left bar is pretty sparse, and I definitely agree that filling it in manually down to H2 is (a) boring and (b) a recipe for errors.

[ia3andy]

I think it looks nice: https://docs.quarkiverse.io/quarkus-renarde/dev/

[holly-cummins]

I agree that the richer navigation on the left is much better than the default. I'm not sure what value the navigation on the right is bringing. It means that to navigate, a user has to flip their attention back and forth between the left and right bars, and a lot of the screen real estate is taken up with repeated content.

I'd suggest, rather than this:

... something like this:

We could add some vertical bar or other divider, and perhaps even some sort of toggle or slider for how many levels to show.

[holly-cummins]

I've just done a quick unscientific survey to see how common the right-bar pattern is. It's the Antora default, which does make it reasonably common.

For example, AWS have it, but they've relabelled the header from 'Content' (which is a totally information-free header) to 'On this page' (which at least gives some indication why there are two nav bars)

Apple do not have two navbars in their developer documentation :)

Microsoft have one navbar and use the right-hand space for extra resources, so that they stay pinned to the top of the page:

Our normal guides have nav on the right, but they do not have nav on the left. That's another option we could do:

[ia3andy]

@gastaldi @FroMage

The left nav is folded and is acting as shortcut to the main sections of the doc, it also helps split the content rather than having one huge monolith.

The right nav is a summary of the content and follow the cursor while scrolling to help navigate it.

[FroMage]

I agree that the richer navigation on the left is much better than the default. I'm not sure what value the navigation on the right is bringing. It means that to navigate, a user has to flip their attention back and forth between the left and right bars, and a lot of the screen real estate is taken up with repeated content.

Ah, totally agree :)

The left nav is folded and is acting as shortcut to the main sections of the doc, it also helps split the content rather than having one huge monolith.

The right nav is a summary of the content and follow the cursor while scrolling to help navigate it.

Spliting is fine. But in my experience the left is not folded, and both follow you. I don't find it helpful to split navigation into two parts arbitrarily.