In-page Table of contents (For all headings)

[enygmator]

ISSUE

This issue (or a similar one) was raised 5 years ago over here.

I want to make it clearer as to exactly what I would love for to be added as a feature as it would be a great interface.

In today's documentation websites, nearly ALL sites have a TOC (table of contents) to the Right-Hand-Side of the page (and sometime to the left), which list all the Headings of the page (i.e. h1, h2, h3, ...) for easier in-page navigation as shown below: (the image is from this site)

Usefulness

It is useful since sometimes you CANNOT divide that page into sub-sections within the MAIN TOC because it doesn't make sense. For example, in a single page we have an explanation of a concept that has a number of sections that make sense only on a single page, then the page might get a bit long, but not long enough to justify splitting it into multiple pages, which requires extensive scrolling to get from one part of the page to another. A simple example

Implementation ideas

I am suggesting that a similar feature be added to this repo:

1. which is enabled by default and can be disabled optionally
2. we can add a button which can hide the in-page TOC

There are a number of design ideas (I obtained from other sites):

Original page

This is the ORIGINAL:

1. We move the left & right page navigation button to the top bar (which makes more sense anyway, since they aren't used too frequently, in my experience), so we now have more screen space
2. Then we add the page TOC to the right hand side with all h1 shown and they can further be expanded to show h2 and they can be expanded to show h3 and so on...
3. This is not shown in picture, but a hamburger menu could toggle the page TOC on and off.

modified page 1

This is a mock UI (not really good looking):

modified page 2

We can further make sure that the left and right page navigation button make more sense by changing the title of the page from the book to that of the page and moving the title of the book into the sidebar (main TOC) as shown in figure below:

These are just suggestions as to the proposed UI. I highly recommend checking out This page and This page to understand the complete experience. I thank this team for considering this feature in advance. I think I followed all guideline

[enygmator]

@Michael-F-Bryan @budziq @steveklabnik @frewsxcv ("If we don't respond in a couple of days, ping us @Michael-F-Bryan, @budziq, @steveklabnik, @frewsxcv it might just be that we forgot" 😉).

[anoadragon453]

Note that there's a bolt-on solution to this feature via https://github.com/JorelAli/mdBook-pagetoc.

But I too would love to see this available as a native option. 🙂

[enygmator]

Thank you @anoadragon453 for the link.

In fact, I just found out that #153 (Add [TOC] support) is a similar feature request which has been solved with another repo (mdbook-preprocessor) which can be found over here - badboy/mdbook-toc. This also means that #153 can be closed (@Michael-F-Bryan , @budziq , @steveklabnik , @frewsxcv )

Another feature request can be found here: #1263 opened by @JorelAli (Thank you for the solution!) which may now be closed.

Also, should this feature request be closed now, or should I leave it open so that this feature gets natively implemented? Maybe, in my spare time, I could try to integrate @JorelAli's solution into md-book and PR it. Any thought repo maintainers?

It seems like this is a popular feature request coming up multiple times over the years (#58 #153 #1263 #1523). Maybe it's time to implement/integrate it. Thank you.

[slowsage]

Published a new preprocessor crate mdbook-pagetoc to wrap the solution by @JorelAli.
Link to repo here.

Steps:

1.  cargo install mdbook-pagetoc
   

2. Then add to book.toml (assuming ./theme is theme directory):

   [preprocessor.pagetoc]
   [output.html]
   additional-css = ["theme/pagetoc.css"]
   additional-js  = ["theme/pagetoc.js"]

3. If using custom index.hbs, add the place marker manually in index.hbs like so:

   <main><div class="sidetoc"><nav class="pagetoc"></nav></div>
       {{{ content }}}
   </main>

Thank you @JorelAli!

[cmpute]

Vote for this! This is especially useful for long pages

Here's a link to Qt docs which made this right.

[RobertZenz]

What might be a neat solution would be to a combination of this and [toc] support. Basically the writer can add [toc] on the top of the document and mdBook generates the table there. If JavaScript is available, it will be moved to the sidebar and "enriched" with marks what header is currently visible on the screen.

I think that would be a neat solution and middle-ground between both features, as the table of contents will be there as well on the print versions, but will be moved to a sidebar if viewed in a browser.

[wade-cheng]

Hi! Wanted to pop in to express my interest in this as well.

In regards to @RobertZenz 's comment on [toc] support: I think the ability to have a table of contents generated by default on all book pages (on web) is important. The OP @enygmator has shown an example of a page where a separate toc is incredibly helpful, and I'd say this is a large class of documentation pages that are written. By supporting this feature natively, and enabled by default, mdBook can benefit those who write documentation with many headings, and not really present a downside to those who write documentation with few headings.

That last point about few headings is an opinion. I think it's helpful to a reader to be able to tell at a glance how long (in sections) a page will be, even if they realize it's not long.

[shenef]

I want to emphasize that the most commonly suggested "solution" was explicitly made to be a temporary workaround.
It is updated infrequently, not fully featured and relies on client side JS to work.
It's also not a crate and instead relies on a manual modification of theme/index.hbs which is currently frequently changed which then necessitates a manual check and/or fix on every mdbook update.
From what I can tell, this is likely the most common reason why a user has a customized index.hbs.