reference: add the API doc grouping engine with tests (dormant)#3320
Merged
Conversation
First slice of the reference rearchitecture (currently one ~11k-page monolith on a single branch), landed in reviewable pieces. This adds the core grouping engine, buildReference, with a unit test suite, but wires it to nothing yet, so there is no site impact. buildReference is a pure function that takes @deno/doc's per-symbol generateHtmlAsJSON output and returns the grouped pages, the old-URL -> new-anchor redirect map, link-rewrite warnings, and a page rewriter. The tests cover the behaviours that are easy to get wrong: category grouping and URLs, redirect collapse of properties to their parent symbol, anchor namespacing, cross-symbol and cross-API-kind link rewriting, Uncategorized ordering, and dead-link reporting. The file also had five stray NUL bytes and an em-dash from its original authoring; both are cleaned up so git treats it as text and it diffs normally.
bartlomieju
added a commit
that referenced
this pull request
Jun 18, 2026
Wires the grouping engine (landed in #3320) into page generation, so the reference ships ~100 grouped pages instead of ~11,000 per-symbol ones. - reference.page.ts now builds one page per Deno/Web category and per Node module, a dense find-in-page index per API kind at /api/<kind>/, and the /api/ tile hub, all from buildReference's output. - the old hand-written landing guides move to /api/<kind>/about/. - every old per-symbol URL is emitted into _site/api/_redirects.json; the middleware (wired up in the previous commit) now serves those 301s, and the hardcoded /api/ -> /api/deno/ redirect is removed so the new hub shows. - the Orama search index points at the new anchored URLs. Verified: reference build is green (105 pages), the redirect map is complete and every one of its 11,222 targets resolves to a real page and anchor, /api/ serves the hub while old symbol URLs 301 to their anchors, and the about pages build alongside the dense indexes. Known follow-ups (separate PRs, pre-existing or cosmetic): Temporal symbols lack category tags so their sidebar entry is orphaned; some overloaded-method summary anchors use @deno/doc's per-method index rather than its global one.
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
1 participant
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.
This is the first bite-sized slice of the API reference rearchitecture.
The full rearchitecture currently lives as one ~1,000-line branch (#3205)
that regroups @deno/doc's ~11,000 per-symbol pages into ~100 grouped
pages. Rather than land that as one hard-to-review diff, I'm peeling it
into a spine of small PRs. This is step 1.
What this adds
reference/_lib/group.ts— the core grouping engine — plus a unit testsuite. It is wired to nothing: no page generation imports it yet, so
there is zero site impact. This lets the gnarliest logic get reviewed and
verified in isolation before any pages change.
buildReferenceis a pure function. Given @deno/doc's per-symbolgenerateHtmlAsJSONoutput for the three API kinds, it returns:Tests
The suite covers the behaviours that are easy to get wrong and that the
later wiring PRs depend on:
Note
The file carried five stray NUL bytes and an em-dash from its original
authoring, which made git treat it as binary (unreviewable diffs). Both
are cleaned up, so it now diffs as normal text.
What's next (separate PRs)
Redirect-middleware plumbing, then the page-generation flip, then the
/api/hub, then small polish follow-ups (category fixes, anchorprecision, search index).