Design a shared cpp-docs: publish the prose, leave the papers alone

Companion to #1. cpp-ci shares the workflows, cpp-build would share the build system, cpp-docs would share the documentation pipeline.

Decision taken up front: prose site first, API reference later or never. There is no Doxygen markup in any of these repositories — not one /// or @brief across xstd's 36 headers. Generating an API site today would produce a list of signatures, which is worse than nothing: it looks like documentation and diverts people from the source, where the actual explanations are. Adding doc comments is per-repo content work that no shared repo can do, so it is not a prerequisite for anything here.

What is already there, and how it has drifted

xstd's doc/ holds four living-or-frozen documents and their renders:

Source	HTML	PDF
N4254.md	✅	—
P0330R0.md	✅	✅
P0330R1.md	✅	✅
ideas.md	—	✅
design.md	—	—

Four documents, four different render combinations, all committed. This is the same drift as the workflows, in a different medium: a manual step nobody ran the same way twice. design.md is the most recently edited file in the directory and has no render at all.

The trap: not everything here should be regenerated

The WG21 papers are artifacts of record, not build outputs. P0330R1.md is dated 2017-10-12 and revises R0. Its committed HTML and PDF are what was submitted to the committee. Regenerating them with a 2026 pandoc would produce a document that differs from the one on WG21's record, for no benefit — and a docs pipeline that "helpfully" rebuilt them would quietly falsify a citation.

So the pipeline has to distinguish two classes:

• Frozen — N4254, P0330R0, P0330R1. Published as-is. The committed renders stay in git precisely because they are the record. Copied into the site, never rebuilt.
• Living — design.md, ideas.md, README.md. Rebuilt on every push. Their committed renders (ideas.pdf) should be deleted from git, since a generated artifact in version control is the thing that drifts.

That split is also why the two markdown dialects in the directory do not collide: the papers use pandoc-flavoured setext headings and indented code blocks, design.md uses GitHub-flavoured ATX headings and inline links. Since the papers are never re-rendered, the generator only ever has to handle GFM.

Proposed shape

cpp-docs carries the theme and configuration:

• MkDocs Material config — handles GFM natively, gives search, navigation, and a dark mode consistent with the rest
• shared CSS, nav conventions, the frozen/living directory convention

cpp-ci gains docs.yml:

• build the living docs, copy the frozen ones verbatim
• actions/deploy-pages to rhalbersma.github.io/<project>

Each repo keeps only its doc/ content and a caller stub.

Known constraint

The Pages deploy needs pages: write and id-token: write. A called workflow can never exceed the caller's token, so this stub needs an explicit permissions: block rather than the four-line shape the sanitizers stub has — the same issue already noted for codeql.yml and scorecard.yml.

Deferred, deliberately

Compiled examples. Docs rot the way copy-pasted workflows do. Examples as real .cpp files that CI compiles, included into the Markdown by reference so a published snippet and a compiling one are the same bytes — the same pattern as test/consumer/. Worth doing, but after there is a site to put them in.

API reference. If doc comments ever get written, Doxygen XML through m.css renders modern C++ far better than stock Doxygen and handles concepts decently. The shared repo would carry the config and theme; the content stays per-repo.

Sequencing

After cpp-ci, alongside or after cpp-build. Lowest blast radius of the three — a broken docs build reddens a badge and publishes nothing, where a broken install rule reaches consumers.

Start by reading the document inventory under xstd's doc/ and the proposed cpp-docs and cpp-ci boundaries. Define how frozen papers are copied verbatim while living Markdown is rebuilt, and inspect the Pages permissions needed by docs.yml. Done means the shared site, caller workflow, navigation, and frozen/living handling are specified and deployable without regenerating the papers.