See discussion thread here: https://discuss.gohugo.io/t/asciidoc-toc-stripped-in-0-15/2231
In 0.15, the TOC (table of con tent) of an asciidoc file is stripped away, while in 0.14 this wasn't the case. This is caused by this commit: https://github.com/spf13/hugo/commit/b23b546a30df792ad2c8f0cf3ec1be30c53ba34d. Would it be possible to make this hardcoded setting configurable?
jbarrez
All 19 comments
Duplicates in a way https://github.com/spf13/hugo/issues/1685. However, that particular issue about docs.
jbarrez
on 8 Dec 2015
I took a first look at the problem, and found some interesting twists.
My first question is: The table of content (TOC) is generated within <body>, not <head>, and shouldn't be stripped by --no-header-footer, which keeps everything inside the <body> intact. Then, what is going on?
It turns out that AsciiDoc does not generate the TOC statically, but rather uses JavaScript to generates the TOC on-the-fly! With the --no-header-footer option, the related JavaScript is not loaded, and
I am happy to report, however, that Asciidoctor is not affected by this issue: Asciidoctor generates the full TOC as static HTML regardless of the --no-header-footer setting. According to http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/#table-of-contents-toc:
- Asciidoctor reifies the ToC in the header of the document instead of relying on JavaScript to create it
So, while we look at how to fix this issue #1687 in Hugo code, could you please install Asciidoctor and give it a try and see using Asciidoctor instead of AsciiDoc solves your problem? :-)
Thanks!
Anthony
anthonyfok
on 16 Dec 2015
Hi Anthony, thanks for digging into this.
We are using asciidoctor, however we were using 1.5.2. Switching to 1.5.3 (and Hugo 0.15), I could see the behaviour you described above: the ToC gets created in the HTML. Had to do some css changes to get it properly on the screen, but all now works as before.
Sorry for your time spent on this - I should have checked if the asciidoctor version was the problem here before thinking it was a Hugo problem.
jbarrez
on 17 Dec 2015
Hi Joram, no need to apologize! In fact, thank you for bringing this to our attention. I would consider it (at least a partial) regression. And I didn't even know the older Asciidoctor 1.5.2 is affected too, and so is AsciiDoc (all versions), so definitely Hugo can check the program name and version too before choosing the right command-line flags. ;-)
Oh! Indeed! Asciidoctor's ToC rendering behaviour is very new. From Asciidoctor's changelog entry for 1.5.3:
- insert toc at default location in embeddable HTML (asciidoctor/asciidoctor#1443)
Thanks again! Re-opening this issue.
Cheers,
Anthony
anthonyfok
on 17 Dec 2015
I would rather have .TableOfContents to work on Asciidoc files than the custom asciidoc(tor) ToC that does not fit into the theme.
Couldn't this be done by parsing the HTML output of asciidoc? It's all <h?> elements with slug ids.
ypnos
on 11 Jan 2016
Could be done? Sure. Will it? Probably not.
bep
on 11 Jan 2016
Does it mean there is no way to get the toc into the sidebar of the hugo learning theme for instance. That would make such combo useless.
PierreR
on 28 Oct 2016
A hacky workaround would be to use regular expressions. This is neither an elegant nor a performent approach but it should do the job. You can use the findRE template function to find headings. findRE returns a list of matches in a given string. The docs feature an example on how this can be done.
digitalcraftsman
on 28 Oct 2016
@digitalcraftsman Thanks for the suggestion. At this point, I will probably leave it for another time hoping a fix will come soonish.
PierreR
on 28 Oct 2016
@anthonyfok what is the status of this? Any prospect of a fix?
bep
on 9 Apr 2017
@anthonyfok what is the status of this? Any prospect of a fix?
bep
on 9 Jun 2017
I prefer Asciidoctor over Markdown for 1 reason: it is expressive enough to describe technical documentation without shortcodes or passed through HTML. I prefer 'pure' markup that transforms to PDF or Kindle when I need that. Hugo is awesome, but guys, not having .TableOfContents is a big deal to .adoc folks. Would you fix that please? Also, make the --safe option configurable. That option cripples things that AsciiDoctor does well. Thank you for listening!
civilin
on 27 Mar 2018
+1 Asciidoctor rules!
jcayouette
on 17 Apr 2018
I posted a workaround here:
theletterf
on 7 Jan 2019
@anthonyfok Anything that could be done to solve this issue? (See my community post)
theletterf
on 25 Jan 2019
This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.
![stale[bot] picture](https://avatars3.githubusercontent.com/in/1724?v=4&s=40)
stale[bot]
on 1 Jun 2019
As an Asciidoctor user, it would be helpful to see this issue addressed. Thanks!
celtic-coder
on 2 Jun 2019
@celtic-coder Do you know about Antora ? That's what I am using these days. Unfortunately AFAIK it is asciidoc only so if you mix markdown and asciidoc you are out of luck.
PierreR
on 2 Jun 2019
Hi @PierreR,
I came across Antora in the past. It looks to be a great project, but since it's main aim appears to be documentation sites, I have not really looked into. Since it is based on AsciiDoc (I have no interest in using Markdown), then I will take a further look. Thanks for the suggestion!
celtic-coder
on 17 Jun 2019
Related issues
ianbrandt
路
3Comments
carandraug
路
3Comments
crash-dive
路
3Comments
moorereason
路
3Comments
vielmetti
路
3Comments
Most helpful comment
As an Asciidoctor user, it would be helpful to see this issue addressed. Thanks!