Discrete Headings: Allow Selective Exclusion from TOC

[tajmone]

Purpose

In very long documents it might useful to selectively exclude some sections from the generated TOC, like Asciidoctor's discrete headings.

How important it is

It would greatly improve control over generated TOCs, allowing to use the full depth of TOC levels without creating needlessly huge TOCs.

For example, if a README doc also contains the full text of a long license with many subsections (e.g. the Artistic License), all its subheadings could be excluded from the generated TOC, showing only "Artistic License" or "License".

Ideal implementation

Maybe exploiting html comments like this:

<!-- discrete -->
## Some Title

The above heading won't be shown in the generated TOC.

Which would be very similar to how discrete headings are implemented in Asciidoctor:

[discrete] 
== Some Title

The above heading won't be shown in the generated TOC.

[naokazuterada]

It looks nice!
I will add it to my TODO list. Thank you.

[TerminalFi]

[discrete] 
== Some Title

The above heading won't be shown in the generated TOC.

Question, how does this work for cases like the below? Would you still expect Heading 3 to be in the TOC?

# Heading 1


<!-- discrete -->
## Heading 2

### Heading 3

[TerminalFi]

I only ask as I have a local copy that I am working on.

[tajmone]

@TheSecEng:

Question, how does this work for cases like the below? Would you still expect Heading 3 to be in the TOC?

Yes, but it would be rendered as a level-2 entry in the TOC, to preserve sequence consistency (and any nested entries will be demoted accordingly).

Taking Asciidoctor as the reference implementation for this feature, if you render this sample document:

= Discrete Headers tests
:sectnums:
:sectnumlevels: 5
:toc: left
:toclevels: 5


== H1 Regular Example

=== H2 Regular Example

==== H3 Regular Example

===== H4 Regular Example

// Same as above, but H3 is out of sequence due to H2 being discrete...

== H1 Normal

[discrete]
=== H2 Discrete

==== H3 Demoted to H2 in TOC

===== H4 Demoted to H3 in TOC

it produces the following TOC:

1. H1 Regular Example
  1.1. H2 Regular Example
    1.1.1. H3 Regular Example
      1.1.1.1. H4 Regular Example
2. H1 Normal
  2.1. H3 Demoted to H2 in TOC
    2.1.1. H4 Demoted to H3 in TOC

In the second H1 TOC-tree, the H3 entry is rendered as if it was an H2, due to the discrete H2 Discrete entry being omitted from the TOC generation, and all other headings are demoted accordingly.

When converting the above example Asciidoctor issues a warning:

$ asciidoctor test.adoc
asciidoctor: WARNING: test.adoc: line 23: section title out of sequence:
expected level 2, got level 3

but it's not an error by any means, and it's shown just in case the author didn't want this to happen.

Discrete headings don't have to abide to section nesting requirements, as mentioned in Asciidoctor Manual, §16.8. Discrete Headings (emphasis added):

A discrete heading is styled in a manner similar to a section title, but is not part of the section hierarchy (i.e., and thus excluded from section nesting requirements), it does not enclose subsequent blocks, and it is not included in the table of contents. The discrete style effectively demotes the section title to a normal heading.

Although the documentation doesn't provide the implementation details on how the final TOC is adjusted, from the above example we can infer that discrete headings are skipped in TOC generation, and that nesting levels are adapted in order to preserve a consistent sequence in the final TOC (regardless of how the actual headings are rendered in the document).

The above example shows that in the final HTML document the actual heading levels are unaffected by the [discrete] — i.e. nesting levels are kept consistent, except that discrete headings are excluded from sections numbering calculations and the TOC — whereas in the generated TOC the hierarchy differs.

That is how Asciidoctor implements the feature. Of course, this package is not bound to follow Asciidoctor, but since the feature is inspired from Asciidoctor I personally think it would make sense to follow its implementation.

[TerminalFi]

@tajmone thanks for the detailed explanation. I will continue to work on my branch and see if I can get this fully working as expected.

[TerminalFi]

@tajmone just wanted to say I should have a PR open today that will support this logic.