Hide header from ToC in Asciidoc / Asciidoctor

Question

I'd like to find a way to hide certain headers from the Table of Contents in my Asciidoc document, which I am processing with Asciidoctor to HTML and PDF.

I have increased the headerlevel value to include some other sub-headers, but a side-effect of this is that some unwanted headers are now also present in the ToC of the output document.

My document is composed dynamically from multiple source files using this kind of statement:

include::deployment/topic.adoc[leveloffset=+3]

Some of these headers should not appear in the ToC - including them would lead to a lot of repetition (they have similar content under each major header).

E.g.:

Each component topic has an H1 header that these 'leveloffset' attributes demote to h2, h3 etc. as required:

= My Topic Title

So my resolved document looks like this:

= Main Title (Keep in ToC)
== H2 (Keep in ToC)
=== H3 (Keep in ToC)
== H2 (Keep in ToC)
=== H3 (Remove from ToC)
== H2 (Keep in ToC)
=== H3 (Remove from ToC)

I can't decrease headerlevel to remove the instances of === H3 (Remove from ToC) without also removing === H3 (Keep in ToC) from the ToC.

I'm trying to keep the document modular. So making some headings simple bold text (using asterisks) is not ideal. I would like to keep them as headers, but add some kind of attribute to them that would mark them as 'non-ToC'.

I'd be grateful for any hints or ideas.

Thanks

Pedlar

Answer 1

I just figured it out - d'oh!

A workable solution is to insert the [discrete] attribute above the header you want to define:

[discrete]
=== H3 (Remove from ToC)
This is the H3 content.

This section of the Asciidoctor docs shows how this attribute is normally used. However, you actually don't need to use an H2 header as it suggests - Asciidoctor respects hierarchical levels when using [discrete], so nesting still works.

Pedlar

It looks like that section of the asciidoctor manual was renamed; this url works: asciidoctor.org/docs/user-manual/#discrete-headings – Ahner