reference: flip API docs to grouped multi-symbol pages#3321
Merged
Conversation
Second slice of the reference rearchitecture. The redirects middleware now also loads _site/api/_redirects.json - the old-per-symbol-URL to new-anchor map produced by the grouping work - and merges it ahead of the existing redirects. The file is not generated yet (a later slice produces it), so this is a no-op today: the middleware logs that it is absent and carries on. Once the page-generation flip lands and the map exists, the 11k old reference URLs start 301ing to their new anchors with no further middleware change. Verified in isolation: with a sample map present the handler returns 301 to the mapped anchor (including the trailing-slash variant) and passes non-redirect requests through untouched.
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.
bartlomieju
changed the title
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 heart of the reference rearchitecture, building on the
grouping engine landed in #3320. It regroups @deno/doc's ~11,000
per-symbol pages into ~100 grouped pages.
What changes
reference.page.tsnow generates one page per Deno/Web category and perNode module, with every symbol documented inline under a stable anchor.
/api/<kind>/becomes a dense, find-in-page-friendly index of everysymbol with a one-line description.
/api/becomes a tile hub across Deno, Web, and Node./api/<kind>/about/._site/api/_redirects.json;the redirects middleware (wired up in the first commit of this PR)
serves those 301s. The hardcoded
/api/->/api/deno/redirect isremoved so the new hub shows.
This PR folds in the redirect-middleware plumbing that was briefly its own
change, since a no-op plumbing PR on its own wasn't worth the review
overhead - it only has meaning alongside this flip. The genuinely
separable piece, the grouping engine, already landed and was reviewed on
its own in #3320.
Verification
real page and a real anchor (0 broken), checked exhaustively.
/api/serves the hub,/api/deno/serves the dense index, and oldper-symbol URLs 301 to their exact anchor (verified end to end through
the middleware).
Known follow-ups (separate polish PRs)
entry links to a page that isn't generated; needs a categorization
fallback or upstream tags.
rather than its global one, so they don't scroll (same-page, pre-existing
upstream, no 404).
Screenshots
API hub:
Dense Deno index:
A Node module page: