Repository navigation
AsciiDoc: section ids rendered wrong #596
Description
AsciiDoc supports TOC, automatic section numbering and specifying explicit IDs for sections.
I created a simple test-page on github showing this:
https://github.com/oasp/oasp-docgen/wiki/asciidoc
As you can see github renders the page incorrect. The hash links in the TOC are correct but the actual IDs in the section a tags are wrong so the TOC links are actually broken:
- ID of section 1 is
user-content-1-section-with-an-id-different-from-its-title. It do not know about thisuser-content-prefix in HTML but it seems that this can be ignored in the hash tag of the URL. However the section number should never be included into a section ID. This makes the ID unstable as if you insert a new section above then all (external) links to the section will break. - Further in the specific case of section 1 an explicit ID is specified. As you can see the link in TOC is correctly rendered as
#sec1but the[[sec1]]syntax is ignored when the ID of the section header is rendered.
It would be extremely cool if the github platform would fix this bugs and behave AsciiDoc compliant here. Maintaining bigger documentations on github with AsciiDoc would become a dream then!
Activity
mojavelinux commentedon Feb 3, 2016
The "user-content" prefix is transparent. @bkeepers explains what's going on in the following blog post. http://opensoul.org/2014/09/05/dom-clobbering/
(tl;dr under the covers, the "user-content" part is stripped away and the ids are properly resolved.)
The problem you are facing has to do with a difference in how IDs are handle between the GitHub html pipeline and Asciidoctor. Basically, the GitHub html pipeline generates its own ids for sections. It doesn't use the ones generated by Asciidoctor. In order to make this work, you have to use the same IDs for sections that the GitHub html pipeline generates. (hence, convincing Asciidoctor to make the right cross references).
I agree this is not ideal. My goal in this comment was to help clarify what is happening.
I definitely want to see that become a reality 👍
hohwille commentedon Feb 3, 2016
Thanks for the hint. So as a workaround, I could apply explicit IDs to each section that exactly match to what github html pipeline is rendering.
Still I consider this as a "bug" in github html pipeline and hope that some day this will be improved as reaction to this issue. Fingers crossed.
mojavelinux commentedon Feb 3, 2016
Basically, yes. You need to get your AsciiDoc document to align with the IDs that the pipeline will ultimately inject into the generated HTML. By setting the two attributes I suggested, you get most of the way there. However, if you have section numbering enabled, then it throws a wrench in it because the html pipeline is putting those numbers into the section ID, coupling the IDs with the numbering.
I agree, the mismatch can often produce incorrect results. However, I just don't know how to get our IDs through the html pipeline sanitizer, so there's not much we can do without buy-in from GitHub.
amarinso commentedon Feb 4, 2016
We have some quite projects already documented on AsciiDoc and it will be a relief not to depend on workarounds to make them property work.
I hope this can be fixed. How can we promote further this issue to GitHub?
mojavelinux commentedon Apr 29, 2016
This problem seems to only affect pages in the wiki (Gollum). The same file in a git repository renders correctly. Perhaps a misconfiguration of the AsciiDoc pipeline in Gollum?
hohwille commentedon Nov 4, 2019
I haven't looked at this for a while but it has been fixed on github already for quite a while. Thanks guys! 👍