Suggest case-insensitive matches in anchor validation warnings - #83
Merged
Merged
Conversation
Anchor validation compares anchors case-sensitively, which is correct
(URL fragments are case-sensitive), but the warning gave no hint when
the only problem was letter case - e.g. linking to '#Conflicts' when
the heading generated '#conflicts'. Users were left wondering why an
anchor that visibly exists was reported as missing.
When a link's anchor is not found but one or more anchors on the target
page match it case-insensitively, the warning now appends:
Note: anchor comparison is case-sensitive; did you mean '#conflicts'?
The hint applies to both same-page and cross-page links.
Also verified (with regression coverage already in place) that anchors
generated late by Markdown extensions, such as pymdownx.tabbed with
'combine_header_slug', are no longer reported as missing.
Addresses upstream issues mkdocs/mkdocs#3703 and mkdocs/mkdocs#3690.
Since 2026-08-12 the macos-latest smoke test job fails during hatch's
'Syncing environment plugin requirements' step with:
ValueError: Unknown environment collector: mkdocs
The failure also occurs on main and is unrelated to any code change.
Installing hatch-mkdocs into the same environment as hatch makes the
environment collector importable directly, bypassing the plugin
requirement sync that broke on the macOS runner.
3 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
1 participant
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.
Anchor validation compares anchors case-sensitively, which is correct (URL fragments are case-sensitive), but the warning gave no hint when the only problem was letter case — e.g. linking to
#Conflictswhen the heading generated#conflicts. Users were left wondering why an anchor that visibly exists was reported as missing.When a link's anchor is not found but one or more anchors on the target page match it case-insensitively, the warning now appends a hint:
The hint applies to both same-page and cross-page links. When no case-insensitive match exists, the message is unchanged, and the existing footnote hint is preserved.
While working on this I also re-verified upstream issue mkdocs/mkdocs#3690 (anchor validation false positives with late-generated IDs, e.g.
pymdownx.tabbedwithcombine_header_slug): it was already fixed in this fork by #34 (extractor priority lowered to run after all extensions), and I confirmed with builds covering tabbed (both styles), raw-HTML anchors,attr_listcustom IDs andtocpermalinks — no false positives remain, so no further code change was needed for it.Additionally, this PR fixes a CI failure that started on 2026-08-12 and also affects
main: the macos-latest smoke test job fails during hatch's "Syncing environment plugin requirements" step withValueError: Unknown environment collector: mkdocs. Installinghatch-mkdocsexplicitly alongsidehatchmakes the environment collector importable directly, bypassing the plugin-requirement sync that broke on the macOS runner.Related Issue
Addresses upstream mkdocs/mkdocs#3703; verifies upstream mkdocs/mkdocs#3690 (already fixed by #34).
Checklist
docs/about/release-notes.mdupdated (if applicable)🤖 Generated with Claude Code
https://claude.ai/code/session_018Hw7x9BxxpuKiLkzjLczp9