Publishing a documentation change
A page is written once in the documentation source and generated into everything else: HTML, a Markdown twin, the machine manifests, the sitemap set and the discovery files. The gate runs before any of it is committed. The generated tree is committed alongside the source, because production serves static files, and IndexNow is told last — after the live pages have been checked.
One source, many outputs#
Nothing in the public corpus is written twice. A page is a plain data record — description, answer, sections, links, search intent, sources — and every published artefact is derived from it. That is the reason a machine fetching the Markdown of a page cannot be told something different from the reader looking at the HTML.
| Output | What it is for |
|---|---|
docs/**/index.html | The canonical public page a person reads |
docs/**/index.md | The Markdown twin of the same page, for clients that prefer text |
research/, developers/ | The engineering notes and the developer and agent surfaces |
docs-data/*.json | The machine manifests: the corpus, the capability status, the index |
sitemaps/*.xml and sitemap.xml | The sitemap set and its index |
llms.txt, llms-full.txt | The short discovery map, and every page's answer paragraph in one file |
Source to live page, stage by stage#
- Trigger — a fact changes, a capability ships, or a page is found to be wrong.
- User event — the change is made in the documentation source: the plan entry, the page record, or the capability registry that both read.
- Authentication and workspace resolution — none. The corpus belongs to the product, not to any workspace, and describes no workspace's data.
- Ingest — the build reads the plan and the content modules and joins them. A planned page with no content, or content for a page nobody planned, is an error rather than a gap.
- Canonical record — the joined page record is the single truth the rest of the build reads.
- Classification — each page's kind decides what it must contain: a workflow needs its stage chain, a technology page must answer whether Connect uses the thing, a troubleshooting page must say what was and was not completed.
- Knowledge and rules — the capability registry supplies every status word and every fact a page is allowed to assert. A claim outside it does not ship.
- Approval — the gate. Word floors, banned machine-writing, keyword stuffing, retired names, forbidden claims, broken links, orphans, duplicate intent. It fails closed.
- Action — generation. HTML, Markdown, manifests, sitemaps and discovery files are written into the web tree.
- Result — the generated tree is committed with the source, because production serves static files and the deploy has no build step.
- Relationship and timeline — user-visible changes reach the changelog and its feed.
- Audit and submission — after the deploy, and after the live pages are verified, the changed URLs are submitted to IndexNow and the submission is logged.
What the gate refuses#
- A planned page with no content, or prose for a page nobody planned.
- A duplicate canonical URL, page id, or primary search query — the last of those is how two pages quietly compete for the same reader.
- A page under the word floor, or missing a required part of its shape.
- A broken internal link, or a page nothing links to.
- Machine-writing phrases, adjective tics and keyword stuffing.
- A retired product name anywhere in the text.
- A forbidden claim, or a capability the registry marks foundation or not-yet described as though it were running.
- Secret-shaped material, or anything that reads like real customer data.
- A workflow page with no stage chain, or a technology page that never says whether Connect uses the technology.
- A public page missing from the sitemaps, or a sitemap listing something that is not a public page.
Why the generated tree is committed#
Because production serves static files and the deploy runs no build. Committing the output makes what is live reviewable in a diff: a change to a sitemap or a manifest is visible before it ships rather than appearing on a server afterwards. It also means a rollback of the documentation is a revert, not a rebuild.
The cost is a larger diff, and it is worth paying. The alternative — generating on the server — puts a build step between a reviewed change and the page a reader sees, and every difference between those two is invisible until somebody reports it.
Order, and the one rule about it#
Submission comes last. Telling an index that a URL changed before the change is live, or when it 404s or redirects, teaches the receiving engine to trust the feed less — and a trusted feed is the entire value of submitting one. Verify the live pages first; the checks that count as verification are on Verifying published documentation.
Questions#
Can a page be published without passing the gate?
Not through this path. The gate fails closed and runs over the whole corpus as well as the page being changed, because a new page can break an old one — by claiming its primary query, or by making an existing link ambiguous.
Why is the Markdown generated rather than written by hand?
So that it cannot disagree with the HTML. A hand-maintained text mirror drifts within weeks, and the drift is invisible to the person reading either version alone. Generating both from one record removes the possibility rather than managing it.
What happens to a URL that is removed?
It leaves the sitemaps in the same build that removes the page, because a sitemap listing something that is not a public page is one of the conditions the gate refuses. Removals are not submitted to IndexNow — that feed is for changed URLs that resolve.