Skip to content

[singlehtml] add docname to section anchor to make them unique #13739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

gastmaier
Copy link

Purpose

Follow up to #13717, inverting the logic, instead of patching the toctree to yield "#id1" instead of "#document-path/to#id1", have the section id to be docname preffixed, solving non-unique ids in singlehtml.
Allows to remove post Sphinx transforms like in here

Top level overview of current behavior

  • ID collision is resolved per doc (#already-used -> #id1, #already-used -> #id2).
  • There is no ID collision resolution on singlehtml step.

Approach taken

Based on the LaTeX builder solution.
sphinx/writers/latex.py#hypertarget[withdoc=True] method suffixes docutils id with the docname.
In my implementation I edit ids['0'] directly to not have to overwrite the whole visit_section method, but I understand if requested to not modify the tree and instead overwrite.

On the format #document-test/extra#id1

It is compatible with HTML anchoring, CSS and JavaScript selectors, but require escaping:

#document-test\/extra\#test {color: #f00;}
document.querySelector('#document-test\\/extra\\#test')

Tests

The following tests are relevant:

  • tests/test_builders/test_build_html_tocdepth.py
  • test_build_html_numfig.py

References

@gastmaier gastmaier force-pushed the toctree-singlehtml2 branch 3 times, most recently from e6b65fb to 5117057 Compare July 20, 2025 14:23
And use modified id directly, modified in the previous commit to ensure
unique id in singlehtml.
@gastmaier gastmaier marked this pull request as ready for review July 21, 2025 07:39
@AA-Turner AA-Turner added the sprint For work completed at a conference or similar event. label Jul 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
sprint For work completed at a conference or similar event.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants