linkcheck: Allow case-insensitive URL comparisons

doc/usage/configuration.rst

@@ -3813,6 +3813,27 @@ and the number of workers to use.
 
    .. versionadded:: 7.3
 
+.. confval:: linkcheck_case_sensitive
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   This setting controls how the *linkcheck* builder decides
+   whether a hyperlink's destination is the same as the URL
+   written in the documentation.
+
+   By default, *linkcheck* requires the destination URL to match the written URL case-sensitively.  This means that a link to ``http://webserver.test/USERNAME`` in
+   the documentation that the server redirects to ``http://webserver.test/username`` will be reported as ``redirected``.
+
+   To allow a more lenient URL comparison, that will report the previous case as
+   ``working`` instead, configure this setting to ``False``.
+
+   .. note::
+
+      HTML anchor checking is always case-sensitive, and is
+      not affected by this setting.
+
+   .. versionadded:: 8.2
+
 .. confval:: linkcheck_rate_limit_timeout
    :type: :code-py:`int`
    :default: :code-py:`300`

sphinx/builders/linkcheck.py

@@ -409,6 +409,7 @@
         self.user_agent = config.user_agent
         self.tls_verify = config.tls_verify
         self.tls_cacerts = config.tls_cacerts
+        self.case_insensitive = not config.linkcheck_case_sensitive
 
         self._session = requests._Session(
             _ignored_redirects=tuple(map(re.compile, config.linkcheck_ignore))
@@ -629,8 +630,24 @@
         netloc = urlsplit(req_url).netloc
         self.rate_limits.pop(netloc, None)
 
+        # Compare URLs, optionally case-insensitively
+        def _normalise_url(url: str) -> str:
+            """Reduces a URL to a normal/equality-comparable form."""
+            normalised_url = url.rstrip('/')
+            if self.case_insensitive:
+                # Only casefold the URL before the fragment; fragments are case-sensitive
+                if '#' in normalised_url:
+                    url_part, fragment = normalised_url.split('#', 1)
+                    normalised_url = url_part.casefold() + '#' + fragment
+                else:
+                    normalised_url = normalised_url.casefold()
+            return normalised_url
+
+        normalised_request_url = _normalise_url(req_url)
+        normalised_response_url = _normalise_url(response_url)
+
         if (
-            (response_url.rstrip('/') == req_url.rstrip('/'))
+            normalised_request_url == normalised_response_url
             or _allowed_redirect(req_url, response_url, self.allowed_redirects)
         ):  # fmt: skip
             return _Status.WORKING, '', 0
@@ -759,6 +776,21 @@
     return None
 
 
+def handle_deprecated_linkcheck_case_config(app: Sphinx, config: Config) -> None:
+    """Handle backward compatibility for renamed linkcheck_case_insensitive config."""
+    # Check if the old config name is used (i.e., user set it to a non-None value)
+    if config.linkcheck_case_insensitive is not None:
+        logger.warning(
+            __(
+                'The configuration value "linkcheck_case_insensitive" is deprecated. '
+                'Use "linkcheck_case_sensitive" instead (with inverted logic: '
+                'linkcheck_case_sensitive = not linkcheck_case_insensitive).'
+            )
+        )
+        # Apply the old config value with inverted logic
+        config.linkcheck_case_sensitive = not config.linkcheck_case_insensitive
+
+
 def compile_linkcheck_allowed_redirects(app: Sphinx, config: Config) -> None:
     """Compile patterns to the regexp objects."""
     if config.linkcheck_allowed_redirects is _SENTINEL_LAR:
@@ -816,10 +848,14 @@
     app.add_config_value(
         'linkcheck_report_timeouts_as_broken', False, '', types=frozenset({bool})
     )
+    app.add_config_value('linkcheck_case_sensitive', True, '', types=frozenset({bool}))
+    # Deprecated config value for backward compatibility
+    app.add_config_value('linkcheck_case_insensitive', None, '', types=frozenset({bool, type(None)}))
 
     app.add_event('linkcheck-process-uri')
 
     # priority 900 to happen after ``check_confval_types()``
+    app.connect('config-inited', handle_deprecated_linkcheck_case_config, priority=899)
     app.connect('config-inited', compile_linkcheck_allowed_redirects, priority=900)
 
     # FIXME: Disable URL rewrite handler for github.com temporarily.

tests/roots/test-linkcheck-case-check/conf.py

@@ -0,0 +1 @@
+# Empty config for linkcheck case sensitivity tests

tests/roots/test-linkcheck-case-check/index.rst

@@ -0,0 +1 @@
+`local server path <http://localhost:7777/path>`_

tests/test_builders/test_build_html_numfig.py

@@ -19,7 +19,6 @@
 
 
 @pytest.mark.sphinx('html', testroot='numfig')
-@pytest.mark.test_params(shared_result='test_build_html_numfig')
 def test_numfig_disabled_warn(app: SphinxTestApp) -> None:
     app.build()
     warnings = app.warning.getvalue()

tests/test_builders/test_build_linkcheck.py

@@ -1439,3 +1439,87 @@ def test_linkcheck_exclude_documents(app: SphinxTestApp) -> None:
         'uri': 'https://www.sphinx-doc.org/this-is-another-broken-link',
         'info': 'br0ken_link matched br[0-9]ken_link from linkcheck_exclude_documents',
     } in content
+
+
+class CaseSensitiveHandler(BaseHTTPRequestHandler):
+    """Simple test server for case sensitivity tests."""
+
+    protocol_version = 'HTTP/1.1'
+
+    def do_HEAD(self):
+        if self.path == '/path':
+            # Redirect lowercase /path to uppercase /Path
+            self.send_response(301, 'Moved Permanently')
+            self.send_header('Location', f'http://{self.headers["Host"]}/Path')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+        elif self.path == '/Path':
+            self.send_response(200, 'OK')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+        else:
+            self.send_response(404, 'Not Found')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+
+    def do_GET(self):
+        if self.path == '/path':
+            # Redirect lowercase /path to uppercase /Path
+            self.send_response(301, 'Moved Permanently')
+            self.send_header('Location', f'http://{self.headers["Host"]}/Path')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+        elif self.path == '/Path':
+            content = b'ok\n\n'
+            self.send_response(200, 'OK')
+            self.send_header('Content-Length', str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        else:
+            self.send_response(404, 'Not Found')
+            self.send_header('Content-Length', '0')
+            self.end_headers()
+
+
+@pytest.mark.sphinx(
+    'linkcheck',
+    testroot='linkcheck-case-check',
+    freshenv=True,
+    confoverrides={'linkcheck_case_sensitive': True},
+)
+def test_linkcheck_case_sensitive(app: SphinxTestApp) -> None:
+    """Test that case-sensitive checking is the default behavior."""
+    with serve_application(app, CaseSensitiveHandler) as address:
+        app.build()
+
+    content = (app.outdir / 'output.json').read_text(encoding='utf8')
+    rows = [json.loads(x) for x in content.splitlines()]
+    rowsby = {row['uri']: row for row in rows}
+
+    # With case-sensitive checking, a URL that redirects to different case
+    # should be marked as redirected
+    lowercase_uri = f'http://{address}/path'
+    assert lowercase_uri in rowsby, f'Expected {lowercase_uri} to be checked'
+    assert rowsby[lowercase_uri]['status'] == 'redirected'
+
+
+@pytest.mark.sphinx(
+    'linkcheck',
+    testroot='linkcheck-case-check',
+    freshenv=True,
+    confoverrides={'linkcheck_case_sensitive': False},
+)
+def test_linkcheck_case_insensitive(app: SphinxTestApp) -> None:
+    """Test that linkcheck_case_sensitive=False ignores case differences in URLs."""
+    with serve_application(app, CaseSensitiveHandler) as address:
+        app.build()
+
+    content = (app.outdir / 'output.json').read_text(encoding='utf8')
+    rows = [json.loads(x) for x in content.splitlines()]
+    rowsby = {row['uri']: row for row in rows}
+
+    # With case-insensitive checking, a URL that differs only in case
+    # should be marked as working
+    lowercase_uri = f'http://{address}/path'
+    assert lowercase_uri in rowsby, f'Expected {lowercase_uri} to be checked'
+    assert rowsby[lowercase_uri]['status'] == 'working'