Publishing repository docs with pinned provenance

Documentation that lives apart from its code rots. Documentation that is scraped from repositories without validation becomes an injection surface. This site’s documentation pipeline is designed around both failure modes: the code owns the docs, and the website trusts nothing it has not verified.

Two parties must agree

Publication requires agreement between two files with different owners:

• The website’s controlled catalog decides which repositories exist at all. A repository cannot add itself to the site.
• Each repository’s .forgeguard/docs.yml manifest decides whether and how its docs/site/ subtree may be published.

Owner, repository, slug, route, and project kind must match between the two, or the build fails. Only docs/site/ is ever eligible — docs/maintainers/ and docs/generated/ are structurally excluded, not just ignored.

Pin, then verify, then publish

At build time the pipeline resolves release tags to commit SHAs and works exclusively from those pinned commits — including reading the manifest itself from the same commit as the content it governs. Every imported file passes through validation that rejects, rather than repairs:

• symlinks and other irregular files in the imported tree;
• .. traversal that escapes the content root, and case-colliding paths;
• executable files and active HTML payloads (scripts, iframes, event handlers, unsafe URL schemes);
• front matter that fails the versioned JSON Schema;
• relative links or images that resolve outside docs/site/;
• duplicate slugs and routes that collide with hand-authored pages.

Anything rejected fails the whole build loudly. A project that breaks its contract disappears from no one’s screen silently — CI turns red instead.

Provenance is part of the page

Every published documentation page carries its source repository, resolved ref, commit SHA, and an “Edit on GitHub” link that targets the exact source commit. A deterministic lock file records each imported file’s hash, so two builds over the same commits produce byte-identical output — and any drift is detectable.

Limitations

The pipeline currently publishes Markdown with a strict raw-HTML allowlist; executable documentation (interactive demos, embedded scripts) is deliberately out of scope. Mermaid diagrams are supported only through build-time rendering, never client-side execution of repository content.