T-BX15-entity-child-pages-anchor-sidebar
Status: closed/done · Impact: medium · Complexity: medium
Make glossary and reference entries clickable on the docs site: every term/reference gets a full child page, the roster cells link through to it, and the sidebar’s Appendix children navigate within the roster pages via row anchors. User-requested follow-on to D-0009-reference-entity-and-docs-appendix §4.
| Location | Role today |
|---|---|
plugin/lib/services/docs/site.ts | Roster pages render entries as plain bold text; no per-entity pages exist |
site/astro.config.mjs | Appendix group holds two flat links (Glossary, References) |
Proposed
Section titled “Proposed”sdlc docs generate site writes one page per entity —
/glossary/<slug>/ and /references/<slug>/ — from the full body
(wikilinks to sibling entities resolve to child routes; other targets
code-format; ^summary markers stripped). Roster cells become
<a id="<slug>"></a>[**Title**](<route>). A generated module
(site/src/generated/appendix_sidebar.mjs) feeds the sidebar collapsed
per-entity children that link to /<roster>/#<slug> anchors.
Approach
Section titled “Approach”entityPageSlug/entityRoutes/transformWikilinks/childPageBodyhelpers insite.ts.regenTermPages+regenReferencePageswith orphan sweeps;regenAppendixSidebarwriting the.mjsmodule.- Roster cells gain the anchor + child link; dry-run inventory grows.
astro.config.mjsimports the module: Appendix → collapsed Glossary/References groups (“All …” overview + anchor children).site/src/routeData.ts(Starlight route middleware) maps the same generated items onto TocItems so the rosters’ “On this page” nav lists every entry (scroll-spy highlights headings only — known limit; navigation works).- Tests: child-page content + cross-link resolution, anchored cells, sidebar module shape, orphan sweep, idempotency; rendered-TOC check via the Astro build.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/lib/services/docs/site.ts | modify | Child pages, routes, wikilink transform, sidebar module, anchored cells |
site/astro.config.mjs | modify | Appendix groups consume the generated module; routeMiddleware registered |
site/src/routeData.ts | new | Maps generated items onto the rosters’ “On this page” TOC |
site/src/generated/appendix_sidebar.mjs | new | Born generated |
site/src/content/docs/glossary/ | new | 13 term child pages (generated) |
site/src/content/docs/references/ | new | 9 reference child pages (generated) |
plugin/lib/services/docs/tests/generate_site.test.ts | modify | P6 suite |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: Every term/reference has a child page; body wikilinks to sibling entities resolve to
child routes; no raw
[[survives. - AC-2: Roster cells link to child routes and carry
<a id>row anchors; the sidebar module exports matching#<slug>anchor links. - AC-3: Orphaned child pages are swept when their entity vanishes.
- AC-4: Astro build green; second
docs generate siterun reportsunchanged. - AC-5: The rosters’ “On this page” lists every term/reference and click-navigates to its row anchor (verified in built HTML).
Out of scope
Section titled “Out of scope”- Child pages for other entity types (decisions, standards, …) — terms and references only.
Dependencies
Section titled “Dependencies”T-8YB9(site roster pages),T-XUTL(live corpus).
Discovery context
Section titled “Discovery context”- User request after testing the D-0009 stack: “make glossary and reference entries click [through to] the full markdown page”, with sidebar children navigating within the roster page and table links going to the child route.
Depends on
Section titled “Depends on”T-8YB9, T-XUTL