feat: list pages and islands

[Mpdreamz]

Summary

Implements a way to create listings/overview pages that automatically lists and groups pages nested pages.

Great if you have data driven docs that you don't want to modify docset.yml for. Also if you have long running branches all trying to append a child in the toc (like our RFC docs) these tend to always merge conflict. This solves that.

  - listing: rfcs
    glob: "**/*.md"
    groups: [release-notes, openapi, frontend, security]
    sort: asc
    visual: all
    island: true

Adds a listing: TOC entry type that glob-discovers documentation files, hides them from the main nav tree, and generates a grouped index page with a client-side filter.

• listing: <path> — declares a listing root; files are discovered via glob: and grouped by listing: frontmatter
• visual: none|groups|all — controls island nav depth: groups only, or groups + pages
• island: true — listing pages get a dedicated sidebar nav instead of the main tree; the listing appears as a single item with a > chevron in the parent nav
• groups: [...] — explicit group ordering with alphabetical fallback
• sort: asc|desc — page order within groups

Overview pages

root
  - index.md <-- H1 and markdown appear before the generated listings and filters
  - group/index.md <-- same but creates the grouping H1 is used as group name
  - group/document.md <-- a doc that will be listed under `group`

Visual

Dictates how much you want to see in the nav of the generated pages, the default is none.

visual: all

visual: groups

visual: none

Island nav

cursorful-video-1785946111134.mp4

An island creates a dedicated navigation for the generated tree, this is great if you have 100s of pages. This allows you to use visual: all in a way that doesn't bloat the overal parent navigation.

Depends on / Related

docs-eng-team usage: elastic/docs-eng-team#735

A first usage of this feature to list our RFCs automatically.

Follow ups

We could extend island: true to - folder in the toc and allow nesting/stacking islands. This would do wonders for our reference docs where we can make e.g all top level items an island so our reference navigation is not HUGE. but also clients or esql could be a sub island because these are HUGE subnavigations of their own.

The other thing this unlocks is a much simpler extension mechanism for e.g detection rules.

Test plan

• dotnet build passes
• ./build.sh unit-test passes
• Point builder at ~/Projects/docs-eng-team/docs with listing: rfcs, visual: all, island: true — RFC index shows grouped cards + filter; island sidebar renders correctly on all pages
• visual: groups — island sidebar shows group headings only (no individual pages)
• island: true + visual: none emits a build error
• Main nav shows listing as single item with > chevron (no children)

🤖 Generated with Claude Code

[theletterf]

The island sidebar will disappear on the first click inside it unless links within the island also swap #secondary-nav via hxSwapOob. Without that, HTMX replaces only the content area and re-fetches the sidebar for the new URL — which resolves to the parent section's tree, not the island. The user loses island context and has no way back except the browser back button.

The nav-v2 branch fixes this by passing hxSwapOob: "#main-container,#secondary-nav" on all links inside an island subtree (IsIslandSubtree = true on NavigationTreeItem). Worth porting that pattern here, especially for large listings where users are expected to navigate between many pages.

[Mpdreamz]

I double checked @theletterf but not sure thats true on main any longer. Navigating and refreshing in and outside the nav works okay from what I can tell.