Skip to content

Conversation

@FazeelUsmani
Copy link

This PR adds a new configuration option linkcheck_ignore_case to enable case-insensitive URL and anchor checking in the linkcheck builder.

Problem

Some web servers (e.g., GitHub, certain hosting platforms) are case-insensitive and may return URLs with different casing than the original link. This causes the linkcheck builder to report false-positive redirects when the URLs differ only in case, even though they point to the same resource.

Solution

  • Added linkcheck_ignore_case boolean configuration option (default: False)
  • Modified URL comparison logic to support case-insensitive matching when enabled
  • Modified anchor comparison in AnchorCheckParser to support case-insensitive matching when enabled
  • Added comprehensive tests for both URL and anchor case-insensitive checking
  • Updated documentation in doc/usage/configuration.rst

@FazeelUsmani FazeelUsmani marked this pull request as draft November 7, 2025 15:08
@jayaddison
Copy link
Contributor

Hi @FazeelUsmani - thank you for developing and describing this pull request.

I have a concern that enabling the option reduces the precision of other hyperlinks that are checked.

Could you explain the use case where it would be easier for a documentation project to enable this option by editing the conf.py instead of fixing the URLs/anchors in their documentation sources to use the correct casing?

@FazeelUsmani FazeelUsmani marked this pull request as ready for review November 10, 2025 08:56
@FazeelUsmani
Copy link
Author

That’s a good point, @jayaddison.
This option is off by default and meant mainly only for large or older docs where many links hit servers that normalise URL casing (like GitHub) or are case-insensitive (like Windows). Enabling it just filters out harmless casing-related redirects so teams can focus on real link issues instead of noise.

@jayaddison
Copy link
Contributor

@FazeelUsmani got it, understood. As often happens, I had a misunderstanding to begin with - you are saying that this only affects whether case-adjusted response URLs are considered to be redirect instead of successful.

Let me think about this a little more; I do understand the value in this now, but am wary of (and trying to think of) any problem side-effects.

@jayaddison
Copy link
Contributor

(also, thank you for the explanation)

@jayaddison
Copy link
Contributor

Separately: I do think that we should probably isolate the redirect-case-sensitivity handling from the HTML anchor case-sensitivity; they seem fairly functionally different from each other to me.

@FazeelUsmani
Copy link
Author

Hmm.. makes sense. I can refactor this into two separate options:
linkcheck_ignore_case_urls: For comparing URL paths (the redirect scenario)
linkcheck_ignore_case_anchors: For comparing HTML anchors

This would give users more granular control. Most users would likely want linkcheck_ignore_case_urls = True (for case-insensitive servers) while keeping linkcheck_ignore_case_anchors = False (since HTML IDs are technically case-sensitive per spec). What do you say?

@AA-Turner
Copy link
Member

AA-Turner commented Nov 10, 2025

Two options seems overkill for this use-case. What do browsers do de facto on case mismatches on fragment IDs?

A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants