Incorrect HTML anchors generated by singlehtml builder

[etrian-dev]

Describe the bug

Using the singlehtml builder to generate index.html from the example below produces invalid internal HTML anchors having multiple # characters in them with certain combinations of glossaries and toctree inclusions. In the reproducer below, there is an index.rst file with a toctree that includes two glossary files in separate documents, each with their own glossary item definition. An equivalent behavior can be observed also by using .. include to include the files directly. The build command is sphinx-build -b singlehtml . _build/foo and the HTML file is tested with html5validator --root _build/foo --show-warnings. Issue #13037 might be related.

How to Reproduce

conf.py:

project = 'Glossary Test'
extensions = []

index.rst:

Main Documentation
==================

Welcome to the documentation.

.. toctree::
   :maxdepth: 2

   ch1
   glossary/term1
   glossary/term2

with the glossary files being trivial items:

.. glossary::

   API
      Lorem Ipsum.

The generate document contains:

<a class="reference internal" href="#document-glossary/term1#term-API"><span class="xref std std-term">API</span></a>

Environment Information

Platform:              linux; (Linux-6.14.0-37-generic-x86_64-with-glibc2.39)
Python version:        3.12.3 (main, Nov  6 2025, 13:44:16) [GCC 13.3.0])
Python implementation: CPython
Sphinx version:        9.0.4
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.19.2

Sphinx extensions

None

Additional context

Some build warnings are generated, but they should not affect the outcome of the test

writing... /home/nicola/test-sphinx/index.rst:6: WARNING: toctree contains reference to document 'glossary/term1' that doesn't have a title: no link will be generated [toc.no_title]
/home/nicola/test-sphinx/index.rst:6: WARNING: toctree contains reference to document 'glossary/term2' that doesn't have a title: no link will be generated [toc.no_title]
/home/nicola/test-sphinx/index.rst:6: WARNING: toctree contains reference to document 'glossary/term1' that doesn't have a title: no link will be generated [toc.no_title]
/home/nicola/test-sphinx/index.rst:6: WARNING: toctree contains reference to document 'glossary/term2' that doesn't have a title: no link will be generated [toc.no_title]

[etrian-dev]

Also found #10106 which seems similar

[jayaddison]

Thanks for the bugreport @etrian-dev - do you know whether this is a regression? (e.g. did a singlehtml build for this project produce functioning hyperlinks in a previous version of Sphinx?)

I'll try to take a look at this within the next week or so.

[etrian-dev]

Hi. This was noticed as part of the build of a large document that uses singlehtml, and does not show issues with Sphinx 8.1.3. After upgrading to 8.2.3 we noticed the problem, but I was able to confirm that it persisted even after that; while I didn't try 8.1.3 on this example, I would expect it to produce correct output, so I would say it is a regression that occurred (or was uncovered by other modifications such as the ones in the aforementioned issue) between 8.1.3 and 8.2.3.

[etrian-dev]

I ran with 8.1.3 in a venv and indeed I see no invalid anchors (the prefix using the document name is absent)

[jayaddison]

Great, thank you - it seems highly likely then that this is indeed a result of PR #13037. I think we should revert that and ideally also add test coverage that would prevent it from passing if it were re-applied. I would still like to deprecate/remove that method, but we'll need to figure out the remaining cases it manages.

[jayaddison]

@etrian-dev I'm having some difficulty replicating the problem - I've created a project with an index, two glossary files in a glossary/ subdirectory, and have copied your provided example contents into those -- but I don't end up with duplicated # characters in the singlehtml output, either from v9.0.4 or from v9.1.0 - I'll keep trying, though.

[nvetrini]

@jayaddison Interesting; what's the content of the hrefs you are getting?

[jayaddison]

@etrian-dev Without titles in the two glossary documents, I do not find any reference internal HREFs at all. If I add titles, then I get output like:

_build/index.html:<li class="toctree-l1"><a class="reference internal" href="#document-glossary/term1">Title</a></li>
_build/index.html:<li class="toctree-l1"><a class="reference internal" href="#document-glossary/term2">Title</a></li>

[etrian-dev]

Chapter One
===========

This chapter discusses :term:`API` design and :term:`REST` principles.

We use :term:`API` throughout our application to communicate between
different services.

Section 1.1
-----------

More details about :term:`REST` architecture here.

The :term:`API` should follow RESTful conventions.

@jayaddison Could you try using this content for ch1.rst?

I get this output with 9.0.4:

<p>This chapter discusses <a class="reference internal" href="#document-glossary/term1#term-API"><span class="xref std std-term">API</span></a> design and <a class="reference internal" href="#document-glossary/term2#term-REST"><span class="xref std std-term">REST</span></a> principles.</p>

and

<p>This chapter discusses <a class="reference internal" href="#term-API"><span class="xref std std-term">API</span></a> design and <a class="reference internal" href="#term-REST"><span class="xref std std-term">REST</span></a> principles.</p>

for 8.1.3.

[jayaddison]

Perfect, thank you @etrian-dev - with that I'm able to get a build with duplicate anchor fragments:

_build/index.html:<p>This chapter discusses <a class="reference internal" href="#document-glossary/term2#term-API"><span class="xref std std-term">API</span></a> design and <span class="xref std std-term">REST</span> principles.</p>
_build/index.html:<p>We use <a class="reference internal" href="#document-glossary/term2#term-API"><span class="xref std std-term">API</span></a> throughout our application to communicate between
_build/index.html:<p>The <a class="reference internal" href="#document-glossary/term2#term-API"><span class="xref std std-term">API</span></a> should follow RESTful conventions.</p>

That should be enough information to construct the test coverage from.

[jayaddison]

So, what fix_refuris seems to be used for is that for hyperlinks that would otherwise feature both a document-path (e.g. #glossary/term1) and also a term-label (e.g. #term-API), it drops the former -- SingleHTMLBuilder is the sole internal user of this. It works because in the resulting HTML, glossary terms -- regardless of the use of fix_refuris -- are emitted solely with the term-label as element ID. The HTML looks like:

<dt id="term-API">...</dt>

So: as a longer-term fix, I'd suggest:

A) Including a document-path part in the glossary term HTML element idenfitiers - e.g. expand them to <dt id="glossary/term1#term-API">...</dt>

AND

B) URLencode the term-label when they are referenced by HREF - e.g. <a href="#document-glossary/term2%23term-API">...</a>

I've tested that proposed approach in Firefox 140.5.0 and it results in functional glossary-term hyperlinks within a single HTML page. As a small bonus, it enables disambiguation of hyperlinks when the same glossary term (e.g. API) is defined in multiple document glossaries.

[jayaddison]

@etrian-dev please could you confirm whether #14241 resolves the problem for you?