How do I augment the ToC?

Previous Topic Next Topic
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view

How do I augment the ToC?

What I'm really after is chunked output, but this isn't going to happen soon (pending since 2013 in issue 626) and I need something for a static website that I need to get up within the next four weeks.

Use case

I plan to have a web site with multiple Asciidoctor-generated HTML files.

The pages are grouped. Say, I have a group "blog", and another group "essays", with subgroups such as "essays - computers" and "essays - cats" (the most important subgroups ).
I can imagine that the groups are defined by subdirectory, or by some attributes inside the .adoc files.

The ToC would look differently in each file; e.g. a blog file would have
    Looking at asciidoctor ***
      Unwrapping ***
      Care and feeding ***
    Looking at asciidoc
    Looking at Hugo
The lines marked *** are supposed to be taken from the normal asciidoctor-generated ToC.

What I already have

I have asciidoctor up and running, generating books and articles in HTML format.

I can do shell scripting, Python and Java programming. (No Ruby, unfortunately.)

Options I considered

1. Set up a bunch of include files for the various parts of the ToC. No idea how to integrate that into the predefined toc mechanism of asciidoctor.
2. Build the toc as a standard element of the web pages. Again, use include files so I don't need to write the same ToC lines again and again.
3. Write an extension that collects all the level-0, level-1 ... titles from the various .adoc files, and generates the matching ToC for a given .adoc file. Normally I'd just do this, but I didn't see an easy way to do this in asciidoctorj (most likely because I haven't spent the time to really learn its API yet).

Any advice?

Reply | Threaded
Open this post in threaded view

Re: How do I augment the ToC?

Reply | Threaded
Open this post in threaded view

Re: How do I augment the ToC?

Alexander Schwartz
Maybe you want to look at static site generators that also accept AsciiDoc. They usually create a ToC from a file structure.

I never used it, but Jekyll-AsciiDoc might get you part of the way:

Depending on the type of site you plan to prepare, Antora might be something for you:

As an example of Antora creating a ToC you can have a look at its own documentation:
* Website with ToC:
* File structure in GitLab:

Cheers, Alexander
Alexander Schwartz (