Proposal: Collapsable nested heading links in navigation: user-defined depth

[christhekeele]

Context

Today, ex_doc renders navigation links for h1, as well as all h2's in a collapsable list, for both documentation and extras.

h2 example from the Tempo docs

It would be nice to have this functionality for deeper headings as well. This could be useful for certain styles of documenting libraries, but very useful for extras: navigating custom guides, livebooks, and cheatsheets. I have wanted this feature often to improve navigation through long guides, especially where:

• certain steps may be optional and the narrative asks users to jump to later points
• the document contains multiple grouped listings of functionality where seeing options and jumping to a specific functionality is desirable

Proposal

I would like to propose making navigation heading depth configurable via setting, to enable deeper navigation into document headings, by allowing users to request navigation heading for headings deeper than 2 (or as shallow as 1), and generating collapsible navigation heading sections accordingly to that limit.

Proposed h3 example from the Tempo docs

This is with the understanding that

• allowing an arbitrary depth may make it easier for a user to configure their documentation in a way that would render navigation poorly (already possible today with just h2s), and they would need to confirm the output of their decision before committing to a depth,
• this would interact with admonitions and tabsets, possibly exposing them to navigation,
• this would interact with the idiomatic Examples block in @doc strings, possibly exposing them to navigation, and
• this would be opt-in, defaulting everywhere to today's depth of 2.

At the project-wide level

Providing a :navigation_heading_depth option that defaults to 2 for ExDoc.Formatter.Config.

At the documentation-wide level

Providing a :docs_navigation_heading_depth option that defaults to 2 for ExDoc.Formatter.Config and overrides :navigation_heading_depth.

At the extras-wide level

Providing a :extras_navigation_heading_depth option that defaults to 2 for ExDoc.Formatter.Config and overrides :navigation_heading_depth.

At the individual Extra level

Providing a :navigation_heading_depth option that defaults to 2 for ExDoc.ExtraNode and overrides the ExDoc.Formatter.Config. This is the key request for this feature, and supporting the above could be implemented later if it proves useful to others.

[josevalim]

Hi @christhekeele. I really don't think we should allow an arbitrary nesting because showing nesting up to h4 or h5 is likely not practical and it would require a lot of code to support it on our side, both frontend and generation (as far as I know, we parse only h2 and h3). That said, I think an early PR exploring how supporting h3 for extras only could be interesting. Feel free to put a coding agent at it because the first goal for now is to validate to see assess the complexity. We should have it only at the project level configuration for now. Thanks!