Repository navigation
ToC links to numbered headings won't work with reStructuredText or AsciiDoc #293
Description
The fragment identifiers for AsciiDoc headings are prefixed with the section number; however, the numbers are omitted from the table of content's links. With ReST, the fragment identifiers for headings are simply bogus (for example, #id203).
Activity
mojavelinux commentedon May 13, 2014
This is pretty frustrating for me as well because the markup pipeline is actively mangling all the references. Since it happens downstream from the processor, there is very little we can do in the markup processors (e.g., Asciidoctor) to prevent this from happening. I'd really like to figure out how we can agree on an approach in the pipeline that doesn't totally mangle the HTML by destroying all of the references.
gjtorikian commentedon May 13, 2014
Can you show an example please? If I'm understanding correctly, the header anchors are messed up, while the links in the docs are correctly pointing to a (now non-existent) anchor?
mojavelinux commentedon May 13, 2014
I was overly vague in my comment. I'll follow up with some specifics. I'll also dive into the pipeline and see if I can understand the nature of the problem better so I can provide more context.
bkeepers commentedon May 27, 2014
The pipeline currently strips out all IDs, and then generates its own anchors for headings. This was originally implemented to prevent DOM clobbering (for example,
<h2 id="addEventListener">would clobberwindow.addEventListenerbecause browsers are awesome). We have since implemented some protection against DOM clobbering, so we could probably go back to allowing IDs in the source markup.mojavelinux commentedon Sep 26, 2014
@bkeepers Perfect explanation @bkeepers. It would be great if, in the AsciiDoc pipeline, the id value was preserved by relocating it to the name attribute. Adding ids after the fact breaks cross references in AsciiDoc since those cross references can be customized. In other words, the pipeline is not aware of the context and is potentially breaking references by using it's own auto-naming strategy.
bkeepers commentedon Sep 26, 2014
I'm working on allowing IDs again. I meant to have it fixed a few weeks ago, but got sidetracked by another project.
🔜
mojavelinux commentedon Sep 26, 2014
Thanks @bkeepers! I'll be on the lookout for updates. If you need any input, just let me know.
richnsoos commentedon Oct 9, 2014
I'm observing the same behavior in our asciidoc. The TOC links don't work unless I remove :numbered:.
The TOC links don't work when :numbered: is included in header.
This works (ie: produces a TOC with links that take the user to the the actual section)
= EAP Framework Documentation =
:toc:
:toc-placement!:
:icons:
:source-highlighter: highlight
toc::[]
This does not work (ie: produces a TOC, but the links don't go anywhere because they don't include the numbers)
= EAP Framework Documentation =
:toc:
:toc-placement!:
:icons:
:numbered:
:source-highlighter: highlight
toc::[]
Creates a hyperlink:
https://github.xxx.xxx.com/sth787/framework/blob/master/userguide/src/main/asciidoc/eapdoc.adoc#introduction
but the Introduction section is actually this:
https://github.xxx.xxx.com/sth787/framework/blob/master/userguide/src/main/asciidoc/eapdoc.adoc#1-introduction
So the TOC link won't resolve.
If I followed this thread correctly, it looks like there is no current solution if we want to keep numbered sections and have a TOC that works, right?
Thanks
mojavelinux commentedon Oct 9, 2014
At the moment, that is correct. We need to align the id generation strategy between core and the HTML pipeline.
Until then, you can disable numbered just on GitHub.
richnsoos commentedon Oct 9, 2014
Thanks for the quick response!
richnsoos commentedon Oct 13, 2014
HI @mojavelinux would this be right spot to ask how to treat non-unique section headings in asciidoc so that the TOC links will work?
We have two different level 5 sections named the same (they are subsections to two different level four sections, which are named differently).
The TOC generates the following for the two different sections that are named the same:
.../eapdoc.adoc#java-configuration
.../eapdoc.adoc#java-configuration-2
But the sections get auto assigned these links:
.../eapdoc.adoc#java-configuration
.../eapdoc.adoc#java-configuration-1
The 1st pair of links work as expected, ie: the TOC link takes the user to the correct section.
The 2nd pair of links don't match, ie: the TOC link of .../eapdoc.adoc#java-configuration-2 won't take user to the .../eapdoc.adoc#java-configuration-1 section.
I'm not sure what process is responsible for generating the links for the sections and the links for the TOC, or how to get them to line up, but is this a behavior that I can control with markup? Apologies if this isn't the correct forum.
Thanks
Update: this is on GitHub Enterprise if it makes any difference
richnsoos commentedon Oct 13, 2014
I must have the wrong spot for this question. :) I suspect the way github markup is rendering the table of contents for a section with a heading that is not unique is possibly flawed. Hoping you guys could help. My research in asciidoc documentation doesn't provide any clues as to why the link in my TOC doesn't work, when all other links in my TOC work as expected. Only difference is that it is a non-unique named heading. Any help pointing me to the correct forum will be appreciated! Thanks
3 remaining items
mojavelinux commentedon Jan 2, 2015
I'll test it out to be sure.
mojavelinux commentedon Jan 6, 2015
Confirmed!
hohwille commentedon Mar 3, 2015
IMHO the actual bug was that in case of :numbered: the numbering is added to the id (anchor). You might have fixed this for :toc: but the problem still is that the number is actually added to the id what makes the id totally unstable and therefore breaks with every new section above. Aint the purpose of an anchor to be stable. Ids are used for bookmarks, deep links and xref: links inside asciidoc.
dcleao commentedon Apr 28, 2016
Still not fixed, for me in AsciiDoc...
dcleao commentedon Apr 28, 2016
@mojavelinux what did you confirm exactly?
hohwille commentedon Apr 28, 2016
See #596
mojavelinux commentedon Apr 29, 2016
@dcleao The following sample file demonstrates that links in the TOC to numbered sections work as expected.
https://github.com/opendevise/asciidoc-samples/blob/master/article.adoc
That's what I confirmed.
mojavelinux commentedon Apr 29, 2016
@dcleao It appears that the TOC works correctly in files in a git repository, but not in the wiki.
dcleao commentedon Apr 29, 2016
@mojavelinux yes, it's in the github wiki that doesn't work for me.
mojavelinux commentedon Apr 29, 2016
@dcleao That means this is a configuration issue in the GitHub deployment. The fact that it works on repositories proves that the software supports this requirement and that the wiki is not configured with the same pipeline. To my knowledge, that configuration is not public, so we'll have to rely on insight from someone at GitHub to correct it.
dhufnagel commentedon Oct 18, 2023
Is this still an issue after 7 years? Or is it an issue again? Because the example does not work for me and other asciidoc TOCs with numbered headings are also not working.
dcleao commentedon Oct 18, 2023
(I've completely lost context of this; have no idea how this is doing)
bmeng commentedon Nov 1, 2023
Seems a regression. I can see the link does not work for now due to the section number added to the hyperlink, but was working in the past years.
dhufnagel commentedon Nov 1, 2023
So should this become a new issue or will this issue be reopened?