Asciidoctor :: Discussion

TOC output using AsciidoctorJ

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

jonbullock

TOC output using AsciidoctorJ

I'm trying to generate a table of contents by using the :toc: attribute in an asciidoc file and render it using AsciidoctorJ v0.1.4 (via JBake) but it doesn't seem to output the table of contents unless I explicitly add toc::[] somewhere in the body of the file. Is this the intended way to add a TOC as trying with the Asciidoctor v0.1.4 CLI using just :toc: works?

Not sure if it's something to do with the way JBake is using AsciidoctorJ so I tried creating a test method for this scenario but I can't seem to get the test suite running properly locally at the moment:

https://github.com/jonbullock/asciidoctor-java-integration/commit/dc1e39859b06a6083871ab5cf148d956aafd3e45

Thanks.

asotobu

Re: TOC output using AsciidoctorJ

It is strange, look my tests https://github.com/asciidoctor/asciidoctorj/blob/master/src/test/java/org/asciidoctor/WhenAttributesAreUsedInAsciidoctor.java#L288

https://github.com/asciidoctor/asciidoctorj/blob/master/src/test/java/org/asciidoctor/WhenAttributesAreUsedInAsciidoctor.java#L247

Both of them are generating toc by set as attribute and not inside document, but I have not tried using :toc: attribute. I will try to write a test too, maybe it is a conjunction of attributes and options which makes that asciidoctor doesn't render it.
@mojavelinux is there any rule in Asciidoctor 0.1.4 that makes a toc not being rendered?

jonbullock

Re: TOC output using AsciidoctorJ

With the release of Asciidoctor v1.5.0 the output of the Table of Contents seems to have slightly changed, to enable TOC output now you have to make sure you unset toc-placement as well as using the toc::[] block macro, where as in the previous release you just had to use the toc::[] block macro.

I thought this situation must be down to the way JBake was using the AsciidoctorJ API, or some combination of options or attributes. Especially as the AsciidoctorJ CLI renders the TOC fine by just adding the :toc: attribute to the document.

After some more testing tonight I've narrowed the different behaviour to the different methods render and renderFlle, this would explain why the CLI works as that uses renderFile and probably why the test you referred to Alex works as that uses renderFile too.

Has anyone else come across this? Is this expected behaviour?

mojavelinux

Re: TOC output using AsciidoctorJ

Administrator

Jon,

It's true that we did make some changes because the previous situation was actually buggy and confusing. Now it's less buggy and a little less confusing, but we still have plans to clean up these attributes even more in the future. They inherit a rather ugly legacy from AsciiDoc Python.

Here's the situation now. In order to use the toc block macro, you need to set the toc attribute to "macro".

[source,asciidoc]

----

:toc: macro

toc::[]

----

Alternatively, you can use the toc-placement attribute:

[source,asciidoc]

----

:toc:

:toc-placement: macro

toc::[]

----

However, my general advice is to key everything off the toc attribute and not use the other attributes because they can sometimes conflict with each other (conceptually) and the results are not always what you expect.

Hope that helps clear things up a bit. This may change how AsciidoctorJ has to set attribute values from the API. I haven't dug into it.

Cheers,

-Dan

On Tue, Sep 30, 2014 at 2:48 PM, jonbullock [via Asciidoctor :: Discussion] <[hidden email]> wrote:

With the release of Asciidoctor v1.5.0 the output of the Table of Contents seems to have slightly changed, to enable TOC output now you have to make sure you unset toc-placement as well as using the toc::[] block macro, where as in the previous release you just had to use the toc::[] block macro.

I thought this situation must be down to the way JBake was using the AsciidoctorJ API, or some combination of options or attributes. Especially as the AsciidoctorJ CLI renders the TOC fine by just adding the :toc: attribute to the document.

After some more testing tonight I've narrowed the different behaviour to the different methods render and renderFlle, this would explain why the CLI works as that uses renderFile and probably why the test you referred to Alex works as that uses renderFile too.

Has anyone else come across this? Is this expected behaviour?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/TOC-output-using-AsciidoctorJ-tp1300p2305.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

jonbullock

Re: TOC output using AsciidoctorJ

Thanks for clearing that up Dan. I've had a few JBake users ask about this recently and now I can point them here for the definitive answer.

Jon