T-QWFA-site-pages-eta-templates
Status: closed/done · Impact: medium · Complexity: medium
Close the idiom split inside the docs service: the site generators
(site.ts, data_model.ts) build pages with inline template
literals, while the wiki artifacts honor the declared contract — TS
assembles plain data, Eta templates own ALL layout. Every site page
moves onto the same split, with byte-identical output as the proof of
equivalence.
| Location | Role today |
|---|---|
plugin/lib/services/docs/generate.ts | Declares the data-to-template split; wiki artifacts honor it via *_template.eta |
plugin/lib/services/docs/site.ts | Skills/entities/ops pages, rosters, child pages, sidebar module — all inline string interpolation (regen.mjs port lineage) |
plugin/lib/services/docs/data_model.ts | Whole page as one template literal, narrative blocks inline |
Proposed
Section titled “Proposed”One site_*.eta template per page kind beside the wiki templates; the
TS keeps only data assembly (rows, cells, flags) and writeIfChanged.
A shared raw render helper (no normalizeWhitespace — site bytes must
not shift). sdlc docs generate site produces zero git diff after the
refactor.
Approach
Section titled “Approach”- Add a raw site-template render helper (own Eta instance,
autoEscape: false,autoTrim: false, no normalization). - Port page kind by page kind — skills, entities, ops, ref index,
glossary roster, references roster, child pages, sidebar module,
data model — verifying zero diff in
site/after each. - Conditional layout (omitted followup tables, empty-corpus
placeholders, optional meta lines) moves into
<% if %>blocks; data objects stay plain. - Tested exports (
collectEntityTypes,renderDataModelPage) keep their signatures.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/lib/services/docs/site.ts | modify | Layout strings out; data assembly + template calls remain |
plugin/lib/services/docs/data_model.ts | modify | Narrative blocks move to the template; derivation stays |
plugin/lib/services/docs/site_*.eta | new | One template per site page kind |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1:
sdlc docs generate siteafter the refactor produces zero git diff undersite/(byte-identical pages). - AC-2: No inline page-layout template literals remain in
site.ts/data_model.ts— layout lives in.etafiles only. - AC-3: Full test battery green; tsc clean; Astro build 124 pages.
Out of scope
Section titled “Out of scope”- Changing any page’s content or layout — this is a pure representation refactor.
- Routing site pages through
normalizeWhitespace(would shift bytes; revisit separately if ever wanted).
Dependencies
Section titled “Dependencies”T-BX15— the child pages and sidebar module it templates landed there.
Discovery context
Section titled “Discovery context”- User review of the D-0009 stack: “are we using inline string
interpolation for some of the templates?” — the regen.mjs port
lineage carried the string-building idiom into
site.ts, and P4–P6 followed the file’s local idiom rather than the service’s declared split.
Depends on
Section titled “Depends on”T-BX15