-
Notifications
You must be signed in to change notification settings - Fork 1
Description
Add an attribute to the [title
node that allows excluding an heading from the TOC — something toc_exclude = true
, where the default would be false
, or toc_include
if that's more inline with the way attributes are defined.
This is inspired by AsciiDoc's discrete headings, which can be enabled via the discrete
attribute on any heading:
[discrete]
== Discrete Heading
In Asciidoctor a discrete heading is still generated as an heading tag (<h1>
..<h6>
), but it's excluded from the TOC, and furthermore:
A discrete heading is declared and styled in a manner similar to that of a section title, but:
- it’s not part of the section hierarchy,
- it can be nested in other blocks,
- it cannot have any child blocks,
- it’s not included in the table of contents.
The above points are important in Asciidoctor, because with real headings you can't skip levels (e.g. jump from <h1>
to <h3>
) or use headings inside blocks (e.g. a quotation block, etc.).
As for PML, I think that the goal should be to simply exclude these headings from the TOC generation and computation process (i.e. as if the discrete headings were simply not there).
It might be worth considering whether any child headings of a discrete heading should be computed or not in the TOC. E.g. the problem is that by excluding a Level-2 heading via discrete, if that section has sub-sections then all the sub-headings would need to be manually set as discrete
too, otherwise there would be a level-gap in the final TOC, where the discrete heading results in a direct jump from Level-1 to Level-3 because it's not being considered in the TOC generation. Unless the TOC ends up considering the next [ch
node as being Level-2 (since in PML chapter nodes don't contain level info, but the level is deduced from their nesting level), which probably doesn't make sense.
So, probably it makes more sense to consider any children of a discrete heading as being discrete too, otherwise the computation of nested TOC levels gets all out of synch.
In any case, this needs to be considered because PML differs from other lightweight markups in this respect, where AsciiDoc and Markdown headings contain in themselves their heading-level info (=
, ==
) whereas in PML is the actual nesting in the final document tree that determines their level.