YATR - Yet Another ToC Request

[Szeraax]

Problem

I think some people are using mdbook as a collection of individual books and don't want to have to manually define all the sub-chapters. Or they don't want each sub-chapter to be on its own individual page (such as when each one may only be a paragraph or two at times). Various issues have been opened up to make it so that you can navigate around via a generated ToC, such as #1523, #1263, and #153, but mkbook-toc and mdbook-pagetoc are useless once you leave the ToC area on any window that is 1122 or fewer pixels wide.

In a world where mdbook is used potentially on windows smaller than 1122px wide, users can't navigate around in longer chapters easily, especially if they don't have a hard keyboard with Home, End, etc.

Proposed Solution

This enhancement differs from other ones in the solution: make it possible for a chapter to have its headers dynamically (at build time or runtime) included in the book navigation on the left side. This would allow someone to specify the markdown file in the summary.md and have the entire chapter stay on 1 page, while the sub headings from that chapter appear like sub-chapters do in the nav bar.

This would likely be most flexible if it could be some front matter in the individual chapter that indicates that all sub-headings in the chapter should be included in the nav on the left, but making it a config setting I think would also be acceptable.

Happy to provide some screenshots if useful.

Notes

Separate from my proposed solution, a good ToC implementation that I like is from Hedgedoc were you either have a nav bar or you have a floating widget that you can tap/click and expand to navigate around the book, including to top or bottom of the current chapter. See example: https://demo.hedgedoc.org/features#. It works great on small windows, large windows, and mobile phones.

[Szeraax]

Well crap. #2201 is just this exactly. #1808 is too! 1808 asks a couple questions about how folding should work:

How does this interact with folding levels? Are those part of the same folding level set as pages, or do they use their own set of levels?

I'd suggest yes, treat the same as sub-chapters for folding sets and rules.

Should this be put behind a global toggle? It may be costly due to requiring a parse of all content files instead of just SUMMARY.md.

A global toggle is fine to enable it.

Should all sections be shown for all pages, or only the current page?

I think this goes back to question 1, but I'd suggest following the rules that already exist (current node is expanded, other nodes collapsed/folded).

[Szeraax]

As another note, I wrote a pre-processor to see if I could create the nav separately of the content and due to the structure of the book object, I believe that a pre-processor CANNOT fulfill the desired solution. I will probably wrote something myself that goes and mucks about in the HTML sidebar nav <ol>.

[diamondburned]

I was able to accomplish this with a pretty silly preprocessor and some homebrewed scripts:

• Preprocessor: https://github.com/diamondburned/docs/blob/main/preprocessors/toc-summary.ts
• Script: https://github.com/diamondburned/docs/blob/main/preprocessors/toc-summary.ts

I would absolutely love to see this supported natively or at least as a complete and non-hacky extension though.