From 51ff9ad03c72a809ce8e1c9c73bea3b3d91795d0 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 6 Sep 2026 18:43:50 +0300 Subject: [PATCH] ci: gate PRs on local links; stop publishing the ADRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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. --- .github/workflows/_checks.yml | 14 ++++++++++++++ mkdocs.yml | 7 ++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.github/workflows/_checks.yml b/.github/workflows/_checks.yml index 7cf9b88..b7d307d 100644 --- a/.github/workflows/_checks.yml +++ b/.github/workflows/_checks.yml @@ -24,6 +24,20 @@ jobs: - uses: extractions/setup-just@v4 - uses: astral-sh/setup-uv@v8.2.0 - run: just docs-build + links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + # --offline blocks network requests and excludes every external URL, so this + # gate is deterministic: it fails only on a relative link or file path that a + # diff actually broke. + - name: Check local links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --offline + --no-progress + '**/*.md' pytest: runs-on: ubuntu-latest diff --git a/mkdocs.yml b/mkdocs.yml index 766fbb5..f3ea0c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,13 +4,10 @@ repo_url: https://github.com/modern-python/faststream-outbox docs_dir: docs edit_uri: edit/main/docs/ -# Agent-facing docs are read from the repo, never published. Keeps `mkdocs --strict` from -# failing them as orphaned pages. +# Agent-facing docs and the ADRs are read from the repo, never published. Keeps +# `mkdocs --strict` from failing them as orphaned pages. exclude_docs: | /agents/ - -# ADRs are built (so their outgoing links are validated) but stay out of the site menu. -not_in_nav: | /adr/ nav: