From 55aeba0d36ef69207499c4d72497c6b4daad0762 Mon Sep 17 00:00:00 2001
From: nkr <42086312+nkr0@users.noreply.github.com>
Date: Tue, 7 Oct 2025 20:40:01 +0200
Subject: [PATCH] allow users to provide a custom label for duplicate names

---
 doc/usage/extensions/autosectionlabel.rst     | 21 +++++++++++++++++++
 sphinx/ext/autosectionlabel.py                |  2 ++
 .../index.rst                                 |  6 ++++++
 .../roots/test-ext-autosectionlabel/index.rst |  6 ++++++
 .../test_ext_autosectionlabel.py              |  6 ++++++
 5 files changed, 41 insertions(+)

diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst
index 161b285a290..a29920cf715 100644
--- a/doc/usage/extensions/autosectionlabel.rst
+++ b/doc/usage/extensions/autosectionlabel.rst
@@ -30,6 +30,27 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be
 used to make headings which appear multiple times but in different documents
 unique.
 
+If a heading appears multiple times in a document, custom labels can be used to
+refer duplicate sections.
+
+For example::
+
+    Section Title
+    -------------
+
+    This is the text of the first section.
+
+    It refers to the section title, see :ref:`Section Title`.
+
+    .. _duplicate_section_title:
+
+    Section Title
+    -------------
+
+    This is the text of the second section.
+
+    It refers to the corresponding section title, see :ref:`duplicate_section_title`.
+
 
 Configuration
 -------------
diff --git a/sphinx/ext/autosectionlabel.py b/sphinx/ext/autosectionlabel.py
index 7c5304ad83d..6553da82de4 100644
--- a/sphinx/ext/autosectionlabel.py
+++ b/sphinx/ext/autosectionlabel.py
@@ -42,6 +42,8 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None:
         docname = app.env.current_document.docname
         title = cast('nodes.title', node[0])
         ref_name = getattr(title, 'rawsource', title.astext())
+        if len(node['ids']) > 1 and node['ids'][-1].startswith('id'):
+            continue
         if app.config.autosectionlabel_prefix_document:
             name = nodes.fully_normalize_name(docname + ':' + ref_name)
         else:
diff --git a/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst b/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst
index d767373c270..bc916fe186e 100644
--- a/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst
+++ b/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst
@@ -9,6 +9,11 @@ Introduce of Sphinx
 Installation
 ============
 
+.. _custom-label:
+
+Installation
+============
+
 For Windows users
 -----------------
 
@@ -30,6 +35,7 @@ References
 
 * :ref:`index:Introduce of Sphinx`
 * :ref:`index:Installation`
+* :ref:`custom-label`
 * :ref:`index:For Windows users`
 * :ref:`index:For UNIX users`
 * :ref:`index:Linux`
diff --git a/tests/roots/test-ext-autosectionlabel/index.rst b/tests/roots/test-ext-autosectionlabel/index.rst
index 133206ed650..8d2145957e7 100644
--- a/tests/roots/test-ext-autosectionlabel/index.rst
+++ b/tests/roots/test-ext-autosectionlabel/index.rst
@@ -9,6 +9,11 @@ Introduce of Sphinx
 Installation
 ============
 
+.. _custom-label:
+
+Installation
+============
+
 For Windows users
 -----------------
 
@@ -30,6 +35,7 @@ References
 * :ref:`test-ext-autosectionlabel`
 * :ref:`Introduce of Sphinx`
 * :ref:`Installation`
+* :ref:`custom-label`
 * :ref:`For Windows users`
 * :ref:`For UNIX users`
 * :ref:`Linux`
diff --git a/tests/test_extensions/test_ext_autosectionlabel.py b/tests/test_extensions/test_ext_autosectionlabel.py
index 28d187a6d67..42f21f1df3d 100644
--- a/tests/test_extensions/test_ext_autosectionlabel.py
+++ b/tests/test_extensions/test_ext_autosectionlabel.py
@@ -28,6 +28,12 @@ def test_autosectionlabel_html(app: SphinxTestApp) -> None:
     )
     assert re.search(html, content, re.DOTALL)
 
+    html = (
+        '<li><p><a class="reference internal" href="#custom-label">'
+        '<span class="std std-ref">Installation</span></a></p></li>'
+    )
+    assert re.search(html, content, re.DOTALL)
+
     html = (
         '<li><p><a class="reference internal" href="#for-windows-users">'
         '<span class="std std-ref">For Windows users</span></a></p></li>'