Skip to content

feat: list pages and islands - #3781

Draft
Mpdreamz wants to merge 7 commits into
mainfrom
feature/toc-listings
Draft

feat: list pages and islands#3781
Mpdreamz wants to merge 7 commits into
mainfrom
feature/toc-listings

Conversation

@Mpdreamz

@Mpdreamz Mpdreamz commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

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

image

visual: groups

image

visual: none

image

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

image

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

Mpdreamz and others added 7 commits August 5, 2026 16:09
@Mpdreamz @claude
feat: listing: TOC entry — glob-driven nav + grouped index pages
2bed7ea 
Adds a new `listing:` entry type for docset.yml / toc.yml that:
- Glob-discovers pages under a folder and registers them in the nav
  tree with Hidden=true (links, prev/next, search all work; nav tree
  does not render them)
- Generates a grouped index page with stacked page-cards, a text
  filter input, and multi-select group chips
- Pages opt into a group via frontmatter `listing: group-name`
  (shorthand) or `listing: {group: group-name}` (mapping form)
- Supports a real index.md at the listing root and per group;
  creates a synthetic page if absent (appends `:::{listing}\n:::`
  to the body)
- Groups ordered by the `groups:` list in the TOC entry, then
  remaining groups alphabetically; unnamed pages rendered last

New files:
- Toc/Listing/ListingFrontMatterReader.cs — frontmatter-only YAML read
- Extensions/Listing/ListingDocsBuilderExtension.cs — auto-enabled
  extension; intercepts real index files; creates synthetic ones
- Extensions/Listing/ListingIndexFile.cs — MarkdownFile subtype that
  appends the listing directive to its content
- Myst/Directives/Listing/ListingBlock.cs — render-time card collection
- Myst/Directives/Listing/ListingView.cshtml — grouped page-cards UI
- Myst/Directives/Listing/ListingViewModel.cs
- Assets/listing.ts — client-side multi-select filter + group chips
- Assets/listing.test.ts — 17 Jest tests (pure predicate + DOM)

Key decisions:
- ExcludeFromIndexing added to INavigationItem (default = Hidden) so
  listing pages are hidden from nav but still indexed for search
- ListingFrontMatterConverter handles both scalar and mapping YAML
- NavigationDocumentationFileLookup uses reference identity; synthetic
  index files must be created directly (not via defaultFileHandling
  which returns ExcludedFile, filtered from Files)
- MarkdownParser constructed before InstantiateExtensions so it can
  be passed to ListingDocsBuilderExtension

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
Add visual: island mode for listing TOC entries
f06b4c6 
When visual: island is set, listing pages are hidden from the main nav
tree but get a dedicated island sidebar nav instead. The island nav
renders a back button linking to the parent root, a flat listing root
entry (using the listing's navigation_title), and all groups with their
pages expanded.

- Add ListingVisual.Island enum value
- Add IslandListingRoot and IsIslandListing to INavigationItem interface
- Set IslandListingRoot on all island listing pages/groups so they render
  the island nav instead of the main tree
- Set IsIslandListing on the listing root FolderNavigation so the index
  page also enters the island nav
- Add IslandNavViewModel, _IslandNav.cshtml for island sidebar rendering
- Wire island nav rendering in both IsolatedBuildNavigationHtmlWriter
  and GlobalNavigationHtmlWriter

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
Move island out of ListingVisual into a separate island: bool
7f906be 
- Remove ListingVisual.Island; island nav is now configured with island: true
  independently of visual: (none|groups|all)
- Add Island bool to ListingOptions; parse island: true/false from YAML
- Validate: island: true + visual: none is an error (listing unreachable)
- groupHidden is now derived from visual: none only, not island status
- Back button in _IslandNav uses full-width outlined button style
  (border-2 border-blue-elastic, w-full)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
visual: now controls island depth, not parent nav visibility
cc39629 
Island listings always show as a single item in the parent nav tree.
The visual: option now controls what the island sidebar renders:
- visual: groups -> island shows group headings only (no pages listed)
- visual: all -> island shows groups with their pages

Parent nav changes:
- Island listing groups are always hidden from the parent tree
- Island folders render a link chevron (right-pointing) instead of
  a toggle, so clicking it navigates into the island

Island nav changes:
- Pages beneath groups only rendered when visual: all
- Visual passed through IslandVisual on FolderNavigation / INavigationItem

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
Back button: grey default, blue on hover
37d02ec 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
Back button: border-2 for slightly bolder border
953ba25 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Mpdreamz @claude
Fix island nav: correct group/page structure and full-width links
e39ba0d 
Three fixes:

1. QueryIndex path-first matching: island groups hide their index page
   so the main nav tree suppresses the group node, but QueryIndex was
   skipping hidden items and picking the first visible content page as
   the folder index. Now QueryIndex checks by SourcePath first
   (visibility-independent) before falling back to the visibility scan.

2. Island nav group headings now use nav-link (flex w-full) instead of
   nav-folder-link, making them full-width clickable like all other nav
   items. Page items under groups use ml-4 indentation.

3. Island chevron in parent nav: remove inline style that was conflicting
   with nav-chevron CSS; the class already applies -rotate-90 (right-
   pointing) by default.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown

Label error. Requires exactly 1 of: automation, breaking, bug, changelog:skip, chore, ci, dependencies, documentation, enhancement, feature, fix, redesign. Found:

@Mpdreamz Mpdreamz changed the title feat: listing: TOC entry with island nav mode feat: list pages and islands Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Mpdreamz