Generate TOC using included files

Hi

Can asciidoctor generate a TOC using files included ?

Example :

## Table of Contents

:toc:

include::01_preface.adoc[]
include::02_introduction.adoc[]
include::03_command1.adoc[]
include::03_command2.adoc[]
include::04_conclusion.adoc[]

Best

Charles

Yes, it will process all included files to generate the TOC based on the titles found. Note the titles depth must be consistent.

But seeing your example I am not sure that is what you are asking, the level 2 title "Table of Contents" with :toc: below is not correct. Maybe you want to generate a toc in a specific part of the document with only certain titles?

Many thanks. Indeed, my example was not correct. The following is good

:toc:

include::01_introduction.adoc[]

## Roles - Features

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent ac nibh ac lectus lobortis molestie sit amet a purus. Cras eu augue a augue maximus fringilla sit amet quis turpis. Phasellus a nisl ut sem fermentum hendrerit. Praesent volutpat pulvinar consequat. Nullam et tellus bibendum, rhoncus dui lobortis, vestibulum neque. Aliquam sit amet egestas nisl. Duis vitae aliquet augue. Integer at bibendum ex. Vestibulum nec nunc quis augue ullamcorper sollicitudin nec quis augue. Morbi purus velit, maximus at fermentum quis, faucibus nec augue. Quisque ac felis finibus, dapibus odio vel, aliquam lacus.

include::02_command.adoc[]

include::03_command.adoc[]

include::04_conclusion.adoc[]

That should workd provided the depth is consistent. That means that if the content included is below a level 2 title like in the example, the sections in the included file (e.g. 02_command.adoc) should be level 3 (###).
Iirc asciidoctor will show some warnings but stilll render something, but you'll see there are errors.

On a side notw, if you want included documents to work independently, have a look at the usage of `leveloffset` in https://asciidoctor.org/docs/user-manual/#include-partitioning.

I was about to start a new thread, but scanned through and found this which seems very much related.

Is it possible to have the root document's TOC consist of links out to those sub-documents, and keep them as separate files, rather than including all the content in one doc?

I know I could just manually edit my own index, but would be nice to just include all the files and have the TOC managed.

I'm just getting started with asciidoctor, it seems like the perfect solution for user documentation when it is a single long document (e.g. intended for output as a printed manual or PDF) but I'm trying to work out how to best use it for managing a collection of separate documents each on their own topic. I expect different users will want to explore down different paths, so in my case it doesn't feel right to just jam it all together into a single doc.

I get the feeling I'm trying to do something which is philosophically different to what asciidoctor is intended for though, so any suggestions appreciated.

Cheers.

You totally got the idea behind asciidoctor, it's oriented to generate a "single long document", but that's by desing, managment of multiple source files to generate multiple outputs is left for other tools.

For what you describe, and perfect result you need a tool like Antora (https://antora.org/, https://docs.antora.org) which is by the same team. The docs site is build with it, so you can grasp and idea of the result. But it has a learning curve if you're starting. Have a look at the demo https://gitlab.com/antora/demo/docs-site.

For a mid level option, you can try lookign into a site/blog generator that supports Asciidoc like jbake or Hugo. Those are more limited but maybe are good enough for what you need.

Below that, you can just use some build tool like the maven, gradle, gulp plugins, or simply so some custom shell scripting on your own. But those treat documents totally independently, so no toc or crossreference options.

Ok thanks for clarifying, I'll look into those options, cheers.

I'm very much loving the syntax and capability of asciidoctor, so hopefully I can find a good and not too complex solution for extending that to a structure of hierarchical docs.

Cheers.