Make docs-site build cleanly on public-sites CI #9
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "initial-development"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
The Astro Starlight shell at docs-site/ was scaffolded in an earlier
commit but never run end-to-end against the real documentation tree.
The fragmented-infra public-sites docs-builder stage hit three
successive errors (pnpm install gate, Starlight config validation,
content schema validation), each surfacing only after the previous one
was patched. This commit gathers every fix into one and adds a local
preview pipeline so future docs-site work catches issues before push.
Package manager:
Docker stage doesn't pull pnpm 11 (whose new approve-builds gate
exits non-zero when sharp / esbuild postinstall scripts run).
belt-and-suspenders for the day the pin moves past pnpm 10.
Starlight config:
0.30's enum) for social.codeberg, which uses the same icon family.
Comment notes the swap target for when @astrojs/starlight is
bumped past 0.34.
Frontmatter injection:
title:frontmatter on everyMarkdown page. None of our source files declare it — neither
hand-written content under documentation/{customer,architecture,
development}/ nor the 350+ doxybook2-generated api-reference
files. Hand-editing is the wrong shape (especially for
auto-generated content), so inject frontmatter at staging time.
injector. Walks a directory, derives
title:from each file'sfirst H1 line (or a humanised filename when no H1 exists), and
prepends a frontmatter block. Idempotent: skips files that already
have frontmatter. Only depends on find / head / grep / sed /
cat / mktemp so it runs in the node:22-slim Docker stage.
Local iteration:
staging against the local working tree. Copies documentation/* into
docs-site/src/content/docs/, optionally regenerates the API
reference (when doxygen / doxybook2 are on PATH), runs the
injector, then pnpm install + pnpm build. Future docs-site work
validates locally without the push-CI-wait loop that drove the
three prior commits.
Ignore housekeeping:
(pnpm 10+) write a lockfile in a different schema version than CI
(corepack-pinned pnpm 9.10.0), so committing it would cause
version-mismatch churn. The Dockerfile uses
pnpm installwithout--frozen-lockfile so dependency resolution happens fresh on every
CI run.
Implementation plan:
2026-05-28-docs-site-real-fix.md: the plan that drove this work,
including the "stop guess-and-push" diagnosis of the prior three
commits' failure mode.
Verified locally with scripts/preview-docs-site.sh: 17 hand-written
pages plus a separately-synthesised doxybook2-shape api-reference
subtree all build cleanly into docs-site/dist/. The companion
fragmented-infra commit (75cc4f5) adds the matching
inject-frontmatter step to the public-sites Dockerfile.
The Astro Starlight shell at docs-site/ was scaffolded in an earlier commit but never run end-to-end against the real documentation tree. The fragmented-infra public-sites docs-builder stage hit three successive errors (pnpm install gate, Starlight config validation, content schema validation), each surfacing only after the previous one was patched. This commit gathers every fix into one and adds a local preview pipeline so future docs-site work catches issues before push. Package manager: - docs-site/package.json: pin packageManager to pnpm@9.10.0 so the Docker stage doesn't pull pnpm 11 (whose new approve-builds gate exits non-zero when sharp / esbuild postinstall scripts run). - Also declare pnpm.onlyBuiltDependencies = [esbuild, sharp] as belt-and-suspenders for the day the pin moves past pnpm 10. Starlight config: - docs-site/astro.config.mjs: swap social.forgejo (not in Starlight 0.30's enum) for social.codeberg, which uses the same icon family. Comment notes the swap target for when @astrojs/starlight is bumped past 0.34. Frontmatter injection: - Starlight's docsSchema() requires `title:` frontmatter on every Markdown page. None of our source files declare it — neither hand-written content under documentation/{customer,architecture, development}/ nor the 350+ doxybook2-generated api-reference files. Hand-editing is the wrong shape (especially for auto-generated content), so inject frontmatter at staging time. - docs-site/scripts/inject-frontmatter.sh: pure-bash recursive injector. Walks a directory, derives `title:` from each file's first H1 line (or a humanised filename when no H1 exists), and prepends a frontmatter block. Idempotent: skips files that already have frontmatter. Only depends on find / head / grep / sed / cat / mktemp so it runs in the node:22-slim Docker stage. Local iteration: - scripts/preview-docs-site.sh: mirrors the Dockerfile's content staging against the local working tree. Copies documentation/* into docs-site/src/content/docs/, optionally regenerates the API reference (when doxygen / doxybook2 are on PATH), runs the injector, then pnpm install + pnpm build. Future docs-site work validates locally without the push-CI-wait loop that drove the three prior commits. Ignore housekeeping: - .gitignore: exclude docs-site/pnpm-lock.yaml. Local installs (pnpm 10+) write a lockfile in a different schema version than CI (corepack-pinned pnpm 9.10.0), so committing it would cause version-mismatch churn. The Dockerfile uses `pnpm install` without --frozen-lockfile so dependency resolution happens fresh on every CI run. Implementation plan: - documentation/agentic-context/implementation-plans/ 2026-05-28-docs-site-real-fix.md: the plan that drove this work, including the "stop guess-and-push" diagnosis of the prior three commits' failure mode. Verified locally with scripts/preview-docs-site.sh: 17 hand-written pages plus a separately-synthesised doxybook2-shape api-reference subtree all build cleanly into docs-site/dist/. The companion fragmented-infra commit (75cc4f5) adds the matching inject-frontmatter step to the public-sites Dockerfile.