AsciiDoc table of contents is not rendered

[lefou]

A AsciiDoc table of contents is not generated, when :toc: is used.

See http://asciidoctor.org/docs/user-manual/#user-toc.

JBake version is 2.2.1-SNAPSHOT, 7be8a72

[Vad1mo]

add this entry to jbake.properties

asciidoctor.option.safe=0

asciidoctor.org is by default in mode 1 or 2 where TOC creation is disabled.

[lefou]

Unfortunately, adding asciidoctor.option.safe=0 doesn't change anything. No TOC is rendered, when the document contains the :toc: attribute.

[jonbullock]

There is an explicit attribute in the AsciidoctorJ library for toc I'll contact the developer to see if this needs setting explicitly in the library rather than on the file.

[Vad1mo]

TOC is working for me. For reference and example check the source of my website here at github.

[jonbullock]

Just had a look at your site source and it looks like the toc only gets rendered if you explicitly add toc::[] where you want the toc to be.

[lefou]

Great, with toc::[] it is at least possible to get the TOC at all. Thanks, for finding out. Unfortunately, all other attributes regarding the TOC (set with :toc:, :toc-placement, etc) will be ignored and can thus be omitted. I didn't find out, how to enable the TOC on the left or right.

Also, with this explicit toc::[] approach, a TOC in an included document and one in the including document result in a page with lots of TOCs in various places.

[lefou]

Apparently, toclevels: is not ignored. So, the missing support for toc-placement: could also be a CSS issue (conflicts between bootstrap and asciidoctor), but that's just a guess.

[Vad1mo]

Layout features depend on the underlying theme/backend. Yet there is no asciidoctor bootstrap theme/backend available. You can see what could be possible at http://laurent-laville.org/asciidoc/bootstrap/manual/current/en/ but unfortunately this is not compatible with asciidoctor.

[Vad1mo]

Wait, I just found this asciidoctor theme https://github.com/nerk/asciidoctor-bs-themes. Seems that someone already made the first step. Tobias @lefou if you try it out could you post us your feedback.

[lefou]

Sure, I will do if I find the time. For now, I can (and have to) live with the current result.

[jonbullock]

I'm checking with the Asciidoctor project on this.

[lefou]

Actually, the table is rendered, if the following two attributes are set:

:toc:
:toc-placement: preambe

Notice, that the default value for toc-placement is auto, not preamble.

Now, if you have a non-empty preamble, you will see the TOC. No need to place the toc::[] macro. But, if your preamble is empty (e.g. no sentence before the first section header), no TOC is rendered. If you use an toc-placement value other than preamble, a TOC is never rendered.

So, one issue is the no-TOC-in-non-preamble problem, which might be caused by a conflict between bootstrap and asciidoctor css, as pointed out before.

For the other issue, no-TOC-if-preamble-is-empty, maybe some Asciidoctor(J) dev can help?

[jonbullock]

Thanks for following this up with more research.

Even if there was a conflict in the CSS, Asciidoctor should still render the HTML for the toc in the source regardless. Just to confuse matters the Asciidoctor CLI will render the toc as expected.

Here's the discussion on this with the Asciidoctor project:

http://discuss.asciidoctor.org/TOC-output-using-AsciidoctorJ-td1300.html

[jonbullock]

TOC output seems to have changed again with the release of Asciidoctor v1.5.0 (#144) however I think I've narrowed it down to the difference in behaviour between render & renderFile methods of the Asciidoctor API.

[richnsoos]

AsciiDoc table of contents is not rendered in my .adoc page on GitHub Enterprise. I tried

toc::[]

and i tried

:toc:
:toc-placement: preamble

... still no TOC.

Is there a text processor involved in the displaying of an adoc file in GitHub/Enterprise? If so, perhaps the AsciiDoctor processor on our Version of GitHub Enterprise needs to be upgraded to support TOCs ...? Just guessing. Any thoughts guys?

[Vad1mo]

@richnsoos what Version of Jbake are you using? see my example in #144 for jBake 2.3.2

[richnsoos]

Not sure, but great question. @roderickrandolph or @busse might know.

[lefou]

@richnsoos Do you have some text in your preamble, or is it empty. The two lines only work, if your preamble is non-empty.

[richnsoos]

@lefou - I sorted it out. It was user error. My toc::[] line was not free standing. It was "connected" to the header so it did not get processed appropriately. As soon as I put a new line above toc::[], it worked. Thanks.

[jonbullock]

As of Asciidoctor v1.5.x the suggested way to include the TOC is:

:toc: macro
...
toc::[]

For more info see: http://discuss.asciidoctor.org/TOC-output-using-AsciidoctorJ-tp1300p2312.html

[nyeates]

I dont pretend to understand what all this is, or what jbake is for that matter, but the TOC stuff is still 'broken' in github public. Thx for workaround!

[laplasz]

if I am using only :toc: macro, then I get a ToC at the left side of the doc - so toc::[] not needed, but without 'macro' value it is not rendered

[hohwille]

It used to work like this:

:toc:
toc::[]

However, it stopped working recently with a silent update of github platform 👎
Is someone still able to get a TOC for Asciidoc on Github wiki?

[jonbullock]

GitHub upgraded to Asciidoctor v1.5.2 recently: https://twitter.com/mojavelinux/status/628344681672241152

See above for solution: #80 (comment)

[Hanserfaust]

As of 2016-02-23, i looked at the examples here to make my TOC work:
https://raw.githubusercontent.com/opendevise/asciidoc-samples/master/demo.adoc

My exact lines to make TOC work was this:

##CUT AND PASTE BELOW THIS LINE##
= Foobar API v1.2
Foobar API documentation.
v1.2, 2016-02-15
:library: Asciidoctor
:idprefix:
:numbered:
:imagesdir: images
:toc: manual
:css-signature: demo
:toc-placement: preamble
//:max-width: 800px
//:doctype: book
//:sectids!:

Any questions regarding the API can be sent to /dev/null.
##CUT AND PASTE ABOVE THIS LINE##

Note that the TOC dit NOT appear if i left out the last line "Any questions...".