ci: gate PRs on local links; stop publishing the ADRs - #165
Merged
Conversation
`mkdocs --strict` validates links inside docs/ only — root Markdown, .github/ and docs/agents/ are unchecked, which AGENTS.md already notes. A relative link breaks because a diff broke it, so the check belongs on the PR that breaks it: --offline blocks network requests and excludes external URLs rather than erroring on them, so the gate is deterministic and cannot flake. That also retires the reason the ADRs were built at all. not_in_nav existed so --strict would validate their outgoing links; the gate now validates them from disk, so they move to exclude_docs and stop being served. Verified: lychee --offline reports 202 OK, 0 errors; `just docs-build` passes and site/adr/ is gone. --include-fragments is deliberately off, and this repo is why. With it on, five links in docs/ fail as "Cannot find fragment" — every one resolves correctly on the built site. lychee computes GitHub-flavoured heading slugs; MkDocs uses python-markdown's, which collapses `Slow handlers — dedicated queue` and `Drain & lifecycle` to a single hyphen where GitHub leaves two. Confirmed against markdown.extensions.toc.slugify. Part of modern-python/.github#66.
Benchmark gate✅ gate passed
Gated (fails the build): |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
mkdocs build --strictvalidates links insidedocs/only. Root Markdown,.github/and
docs/agents/are unchecked —AGENTS.mdalready says so. Nothing catchesa broken relative link in
AGENTS.md,CONTEXT.md, or the README.A relative link breaks because a diff broke it. Unlike an external URL it needs no network
and cannot flake, so it belongs on the PR that breaks it rather than in a scheduled job.
Design
One job in
_checks.yml, so it runs wherever_checks.ymlalready runs.--offlineblocksall network requests and excludes external URLs rather than erroring on them, which is
what makes the gate deterministic and safe to block on. No exclusions, no token, no schedule.
The ADRs stop being published.
not_in_navexisted for exactly one reason — build themso
--strictvalidates their outgoing links. The gate does that now, from disk, so/adr/moves to
exclude_docs.Non-goals
No external link checking here. That runs weekly in
modern-python/.githuband staysthere; sharing it across repos was considered and rejected (Offer the link checker to the other repos as a reusable workflow .github#64).
--include-fragmentsstays off — and this repo is the reason. Turning it on failsfive links in
docs/asCannot find fragment, and all five resolve correctly on thebuilt site:
Slow handlers — dedicated queueslow-handlers-dedicated-queueDrain & lifecycledrain-lifecyclevs. FastStream + `KafkaBroker` / `RabbitBroker` directlyvs-faststream-kafkabroker-rabbitbroker-directlylychee computes GitHub-flavoured slugs, which leave a doubled hyphen where an em dash,
&or backticks were. Verified by runningmarkdown.extensions.toc.slugifydirectly.Verification
lychee --offlineon this tree: 241 total, 202 OK, 0 errors — the gate lands green.just docs-buildpasses, andsite/adr/is confirmed absent from the build.Before merging
and Add the offline link gate to the 18 green repos, and unpublish the ADRs in the two that have them .github#66, where it applies to 18 repos rather than only this one.
just lint-ci/just test— not run; this diff touches only CI config andmkdocs.yml.