Markup: ToC links to numbered headings won't work with reStructuredText or AsciiDoc

[ianbollinger]

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).

[mojavelinux]

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]

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]

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]

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 clobber window.addEventListener because 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]

@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]

I'm working on allowing IDs again. I meant to have it fixed a few weeks ago, but got sidetracked by another project.

:soon:

[mojavelinux]

Thanks @bkeepers! I'll be on the lookout for updates. If you need any input, just let me know.

[richnsoos]

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]

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?

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.

ifndef::env-github[:numbered:]

[richnsoos]

Thanks for the quick response!

[richnsoos]

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]

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

[richnsoos]

Maybe starting a new issue is the way to go (https://github.com/github/markup/issues/383) .... don't want to mix issues. Thanks timbo for trying to help!

[bkeepers]

I think this is the same issue as https://github.com/github/markup/issues/71 and should be fixed by https://github.com/github/markup/pull/391

[mojavelinux]

I'll test it out to be sure.

[mojavelinux]

Confirmed!

[hohwille]

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]

Still not fixed, for me in AsciiDoc...

[dcleao]

@mojavelinux what did you confirm exactly?

[hohwille]

See #596

[mojavelinux]

@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]

@dcleao It appears that the TOC works correctly in files in a git repository, but not in the wiki.

[dcleao]

@mojavelinux yes, it's in the github wiki that doesn't work for me.

[mojavelinux]

@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.