fix: move the build banner to the footer, link the canonical site, declare the sitemap (#691, #692)

[raeq]

Closes #691. Closes #692.

Three problems reported from the live site, plus the robots.txt gap filed alongside them.

The banner was too prominent, on all 91 pages

#641 injected it as an !!! info admonition under each page's first H1, so a five-line box
came between the title and the first sentence of every page. The facts earn a place on
every page. They do not earn that one.

on_page_markdown is gone. scripts/mkdocs_build_banner.py publishes both facts into
config.extra through on_config, and overrides/main.html renders them once in the
footer. The readthedocs theme ships a main.html whose entire content is a comment
saying customisations belong there, so this is the sanctioned extension point rather than a
copied template that drifts when mkdocs updates.

It named a version two releases stale, and the hook was not at fault

The site said 0.14.0; the release is 0.14.1.

docs.yml is path-filtered. Its last deploy ran at 4c54aa1, the release-PR merge, and CI
resolves the version by asking PyPI at build time — which still served 0.14.0, because
the tag came minutes later. Nothing rebuilt the site afterwards: #686 touched
RELEASING.md and #688 touched a workflow, neither matching the filter.

So publishing a release never refreshed the page that states which release exists, which is
the one moment that statement changes. docs.yml now also runs on release: [published].
Checked rather than assumed: the deploy step gates on credentials, not on ref, and non-PR
events already deploy with --branch=main, so a release event produces a production
deploy.

Nothing linked disarm.dev, and canonical was the wrong tool for it

$ grep -rn "https://disarm.dev" docs/ mkdocs.yml README.md
(no matches)

Both sites are live and distinct, and nothing connected them in either direction. The
footer links it now, with og:site_name and a schema.org isPartOf naming it the parent.

Not done by repointing rel=canonical, which is what was asked for. base.html emits
a correct self-referential canonical per page. Aiming those at the landing site declares
all 91 pages duplicates of it, and the usual outcome is the docs dropping out of results
for their own content — the opposite of the goal. A test asserts the override emits no
canonical of its own.

robots.txt

With none of its own, Cloudflare served a managed file that was the Content Signals
explanatory preamble and nothing else: no User-agent, no Allow, no Sitemap, and no
actual signals. The 75-page sitemap MkDocs writes on every build was undeclared.

docs/ is copied to the site root, as docs/_redirects already relied on, so
docs/robots.txt lands at /robots.txt with no change to mkdocs.yml or the workflow.
The managed preamble goes with it, which loses nothing operative. Content Signals, if
wanted, belong there as explicit Content-Signal: lines rather than inherited by default.

Tests

The five that pinned the old injection are replaced, not dropped. The new ones cover
on_config publishing both facts, absent facts staying None so the template renders
nothing rather than a sentence of blanks, and extra surviving another owner.

Two are coverage the old design could not have: that the template still reads the keys the
hook writes, and that mkdocs.yml still points at overrides/. A hook publishing a fact
nothing reads is an empty footer that looks exactly like a working one.

Each guard confirmed to fail when perturbed:

perturbation	test that fired
drop custom_dir from mkdocs.yml	test_the_override_exists_and_is_wired_in
rename config.extra.build_commit in the template	test_the_template_reads_what_the_hook_writes[build_commit]
add a rel="canonical" to the override	test_it_does_not_rewrite_the_canonical_url

Verification

gate	result
pytest	4500 passed, 29 skipped
ruff check / format --check (CI's pinned 0.15.17)	clean
mypy python/disarm	clean
scripts/generate_docs_index.sh --check	up to date
mkdocs build --strict	built
scripts/run_doc_tests.py	all 39 doc pages passed

Built-output checks:

$ cat site/robots.txt | grep -i sitemap
Sitemap: https://docs.disarm.dev/sitemap.xml

$ grep -c '<loc>' site/sitemap.xml
75

$ grep -o '<link rel="canonical"[^>]*>' site/user-guide/slugification.html
<link rel="canonical" href="https://docs.disarm.dev/user-guide/slugification.html" />

$ grep -c admonition site/user-guide/slugification.html
0

The footer renders: Built from main at 82dd777. The published release is 0.14.1.
Anything documented here that landed after it is not yet in pip install disarm. The
JSON-LD parses.

[github-actions]

📄 Docs preview: https://cac08604.disarm-docs.pages.dev

[Copilot]

🟡 Changes recommended

The new release: published docs workflow trigger can cause production docs to be built from the release tag commit (not main) unless checkout/ref handling is adjusted, which risks deploying stale docs content.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adjusts the docs site’s provenance messaging and cross-site SEO signals by moving the build “banner” into a single footer-rendered element, adding a canonical-site link/metadata to connect docs.disarm.dev to disarm.dev, and ensuring the sitemap is declared via an origin robots.txt. It also updates CI so docs can rebuild when a release is published (so the “latest release” fact stays current).

Changes:

• Replace per-page Markdown injection with an on_config hook that publishes build provenance into config.extra, rendered once via a ReadTheDocs theme override.
• Add footer link + OpenGraph/JSON-LD isPartOf metadata connecting docs to https://disarm.dev/, without rewriting per-page canonical URLs.
• Add docs/robots.txt to declare the MkDocs sitemap, and trigger docs workflow on release: published.

File summaries

File	Description
scripts/mkdocs_build_banner.py	Switch from on_page_markdown injection to on_config publishing provenance into config.extra.
overrides/main.html	Add theme override for footer provenance rendering and cross-site OG/JSON-LD metadata.
mkdocs.yml	Wire in custom_dir: overrides/, update footer copyright to link disarm.dev.
docs/robots.txt	Provide origin robots.txt that declares the sitemap.
.github/workflows/docs.yml	Add release: published trigger so docs rebuild when a release is published.
tests/test_docs_release_drift.py	Replace placement tests with guards for hook/template wiring and canonical preservation.
CHANGELOG.md	Document the banner/footer/robots changes under Unreleased.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.