Build docs and run integration tests against this checkout

[shenxianpeng]

The release-notes page rendered mkdocs, version 1.6.1 after #92's version-substitution hook went live. That value was correct — and that was the problem: the published docs site was being built by the upstream release, not by this project. Investigating turned up a second, worse instance of the same fault.

Root cause

The docs and integration environments derive their dependencies from mkdocs.yml, and every documentation plugin requires the upstream mkdocs distribution by name (mkdocs-autorefs, mkdocstrings, mkdocs-literate-nav, mkdocs-redirects all declare Requires-Dist: mkdocs), so it cannot be avoided by editing our own dependency list. That distribution ships a package of the same name as this project and is installed after it, so its files win in site-packages for anything resolved through the console script.

Two things were silently running the wrong code:

• hatch run docs:build / docs:deploy — the published site was built by the upstream release.
• hatch run integration:test — the runner shells out to mkdocs build from the fixture directories (mkdocs/tests/integration.py), so the integration suite has been exercising the upstream release while reporting green.

Fix

[tool.hatch.envs.docs]
env-vars = { PYTHONPATH = "{root}" }

(and the same for integration). Hatch applies env-vars around dependency syncing and command execution alike, and PYTHONPATH precedes site-packages on sys.path, so the console script and every subprocess it spawns resolve to this checkout. The upstream distribution stays installed, so the plugins' requirements remain satisfied and Hatch's dependency check stays in sync — nothing is fought, reinstalled, or removed.

This replaces the earlier revision of this PR, which prefixed every docs script with a pip install --force-reinstall. That approach worked but was imperative, ran on every invocation, and left the environment holding a copy of the sources (so docs:serve would not reflect edits). Alternatives ruled out while investigating: Hatch's pre-/post-install-commands run before dependency syncing and only at environment creation, so they cannot win this race; Hatch 1.18's sources redirects dependencies by distribution name, which cannot match mkdocs → mkdocs-ng; and neither the collector nor Hatch offers any way to exclude a transitive requirement.

Regression guard

mkdocs/tests/integration.py now asserts up front that the mkdocs command it is about to invoke is the same code the tests were loaded from, so a silent recurrence becomes a loud failure:

Error: The 'mkdocs' command runs /.../site-packages/mkdocs, but these tests are for
/home/user/mkdocs/mkdocs. Run them through 'hatch run integration:test', which puts
the project first on sys.path.

Verification

From a pruned docs environment, rebuilt exactly as CI does:

• site-packages contains upstream mkdocs 1.6.1 (real files) alongside mkdocs_ng-1.8.0.dist-info — the collision is still there, as expected
• the built release-notes page nonetheless renders 1.8.0, i.e. the build used this checkout
• hatch run +py=3.11 +type=default integration:test passes with the guard active
• negative test: running the same runner with PYTHONPATH stripped makes the guard fire with the message above
• ruff/isort clean; unit suite unchanged (only the 4 pre-existing localization failures in this container)

Note for later

The same name collision affects end users who install mkdocs-ng alongside any plugin that requires mkdocs — the winner depends on install order. That needs a packaging-level answer and deserves its own issue; this PR fixes only our own pipelines.

Checklist

• New tests added for new behavior (if applicable) — integration-runner guard
• Documentation updated (if applicable) — not applicable
• Release notes docs/about/release-notes.md updated (if applicable) — not applicable, build infrastructure only

🤖 Generated with Claude Code

https://claude.ai/code/session_018Hw7x9BxxpuKiLkzjLczp9

[codspeed-hq]

Merging this PR will improve performance by 14.56%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 27 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_get_yaml_loader	394.6 µs	344.5 µs	+14.56%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/mkdocs-issue-4167-15dhse (412c9cd) with main (9cf3048)}