Repository navigation
feat(docs): mirror documentation folders in the sidebar - #53
Merged
Merged
Conversation
ZodSharp publishes its prerelease pages in topic folders, and ADR 0011 made a folder a path segment of the published URL - but the sidebar still flattened the list, so the hierarchy existed only in the address. - buildChannelItems nests a channel's pages into Starlight groups, one per folder, placed where the folder's first page appears so the sync's reading order survives; a nested index.md links the folder's own address. - Each aggregated page names its section above the title, in the same spelling. - docsPageRedirects forwards a moved page from every base the project publishes, so the flat prerelease URLs published today do not 404 when the folders land. - A flat corpus renders exactly as before: no group, no section trail. Tests cover flat corpora, group placement and order, deep nesting, folder indexes, label spelling, per-channel redirects and the built HTML.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
ZodSharp's prerelease docs (on
main) now live in topic folders, and ADR 0011 already made a folder a path segment of the published URL. The display did not follow: the docs sidebar was still one flat list of thirty links, a page said nothing about the section it belonged to, and the flat prerelease URLs published today were about to 404 becausedocs.redirectsonly emitted pairs for the default channel.What
src/lib/docs/sidebar.ts) -buildChannelItems()returnsSidebarDocItem[](SidebarSlugEntry | SidebarGroupEntry) and nests each slug's folders into Starlight groups. A folder appears where its first page appears and absorbs its later pages, so the sync's reading order (docs.order/_Sidebar.md) survives; nesting is recursive; a folder'sindex.mdlinks the folder's own address instead of a non-existent/index/slug.PageTitle.astro) - a tracked-uppercase trail above the<h1>, absent at the docs root.global.css) - a nested group label is reduced to a section label (Starlight styles every group label like a top-level heading, which made a folder read like a second project).redirects.ts) - eachdocsPageRedirectspair is emitted under every base the project publishes (/docs/<id>/and/docs/<id>/prerelease/); the existing guards still decide which pairs are real.AGENTS.mdand thedocs-aggregation-rulesskill describe the nested sidebar, the section trail and per-channel forwarding.A flat corpus is unchanged: no folder in any slug means no group and no section trail.
Result
Seven groups for ZodSharp's seven source folders.
/docs/zodsharp/prerelease/string-validation/is now anoindexmeta refresh toschemas/string-validation/(30 moved pages), while thelivechannel (tagv2.4.2, which predates the move) still renders flat with no redirect shadowing it.Tests
group-labelper folder (and none when flat), nested links carry the hierarchical URL, and the section trail appears only on nested pages.Validation
format:check,lint,typecheck(0 errors),bun test tests/unit(335 pass),check:assets,check:projects,build(276 pages, all internal links valid),discovery:validate,check:links,check:generated,test:dist(42 pass, 2 skipped for the promotion-only assertions) - all green, against a docs mirror regenerated by a livedata:sync.