Add linkcheck_case_sensitive configuration option

doc/usage/configuration.rst

@@ -3813,6 +3813,30 @@ 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 @@ def __init__(
         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 @@ def _check_uri(self, uri: str, hyperlink: Hyperlink) -> _URIProperties:
         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
@@ -816,6 +833,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value(
         'linkcheck_report_timeouts_as_broken', False, '', types=frozenset({bool})
     )
+    app.add_config_value('linkcheck_case_sensitive', True, '', types=frozenset({bool}))
 
     app.add_event('linkcheck-process-uri')
 

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', '/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'