Custom `toclevels` / option to keep full TOC

[cod3licious]

On the one hand I think it's really neat that the TOC is collapsed/expanded as needed, however, it would be even better if the default collapsed state could be customized. Alternatively, the default TOC representaion should be the same as the value for :multipage-level:, i.e., such that each of the individual pages can be seen and clicked in the TOC directly. For example, right now with :multipage-level: 2 it takes me two clicks to reach a specific section page, since I can only click the chapter in the TOC and then need to wait until it expanded to find the section.

[owenh000]

@cod3licious, thanks for the suggestion.

A multipage-toc document attribute could be added with support for options such as:

• full: show complete ToC on every page (stock Asciidoctor behavior)
• collapse: include all parent sections of the current page and their siblings (current behavior)
• pages: include an entry for each page (each page is directly accessible from the ToC on any other page)

There might be better names. All behavior would need to be checked for interactions with the toclevels document attribute and any other related behavior.

Does this seem to fit?

[cod3licious]

I think this is going in the right direction, but what I think would be coolest is to have the option of what you call page and collapsed kind of combined.

So maybe it might be easiest to add an additional collapsed-toclevels attribute that specifies the levels that should be show for the collapsed part and then the normal toclevels indicate the levels for the non-collapsed part (as is being done right now). This would add greater flexibility. One should probably only make sure that collapsed-toclevels <= toclevels, or give a warning if not, since it would be really weird if elements of the toc vanish when you click on them.

[owenh000]

To avoid namespace trouble it might be better to call this multipage-collapsed-toclevels. So I'll use that below.

If I understand correctly, multipage-collapsed-toclevels would be a document attribute like toclevels:

• The stock toclevels attribute controls the ToC depth for the current page (like the entire document in stock Asciidoctor).
• The proposed multipage-collapsed-toclevels attribute controls the minimum ToC depth for anything not on the current page.

The current minimum depth behavior of "include all parent sections of the current page and their siblings, plus the sections in the current page specified by the toclevels document attribute" would I think be equivalent to :multipage-collapsed-toclevels: 0. Not accepting a value less than toclevels would make the minimum depth behavior unavailable. Rather the code should always automatically raise multipage-collapsed-toclevels as necessary per page to satisfy the minimum depth requirements. That's how I'm seeing it right now at least.

This behavior seems better to me than what I described earlier. Maybe this can help guide development on this if someone gets an opportunity to work on it (my available time for working on asciidoctor-multipage is very limited without sponsors).

[jamesread]

Hey @owenh000 , would love to see this issue implemented - I rely on asciidoctor-multipage for http://docs.olivetin.app , as-well as http://docs.upsilonproject.io . I've just added a one-time sponsor to say thanks for your work on this project, and hopefully you can find some time for implementing this!