Skip to content

Building the static intranet + automating the archive manifest

Guide

Building the static intranet + automating the archive manifest

  • Date: 2026-05-30 · By: Delivery / Operations / The Archives

What we learned

Archive manifest automation. The recurring toil flagged by the 360 review was hand-editing SHA-256 checksums. scripts/archive-manifest.sh reads the doc→source mapping from the manifest itself (the latest rows), then verifies/refreshes hashes — no separate mapping file to drift. verify is read-only (wired into session-end); update refreshes after changes. Adding a new doc still authors one row pair once; everything after is automated.

Repo-first static portal (Astro). Keep the app in intranet/ and treat the repo as the single source of truth: a build-time sync-content.mjs generates src/generated/ from the repo. Wins:

  • Render markdown with markdown-it (html:false) so repo placeholders like <doc> and {{PROJECT_NAME}} show as literal text instead of breaking parsing.
  • Bundle Mermaid (npm dep), don’t CDN it — the page-context CDN fetch was blocked, and bundling makes diagrams render offline/local-first.
  • In Astro, getStaticPaths is hoisted into its own scope — put import.meta.glob(...) inside the function, not at module top.
  • One HTML entity (&amp;) survives templating into diagram source; fix it in the client before mermaid.run().

Mermaid validator gotcha. Keep classDef and class on separate lines (no classDef ...; class ... one-liner) or validation fails.

Why it matters

Lean, low-toil patterns that scale: the record maintains itself, and the front end stays in sync with the repo automatically.

Next time

  • Reuse sync-content.mjs as the template for any new repo-driven surface.
  • When deploying the intranet, add the password gate + Supabase/SSO (ADR-0006).

Promotion (curator note, added 2026-06-01)

  • Promoted to / superseded-forward by: the durable intranet build/deploy constants are now carried in docs/knowledge/2026-06-01-intranet-build-and-deploy-constraints.md (which extends this entry) and from there into the Engineering playbook (docs/units/engineering/playbook.md) and job aids (JA-056, JA-058). The archive-automation learnings are promoted into the Archives SOPs (docs/sop/SOP-010-preservation-omni-intake.md, SOP-011-archive-integrity-verification.md).
  • Supersedes / superseded by: none — extended (not superseded) by the 2026-06-01 constraints entry.