Current page's table of contents

[Thibaut]

Some documentations have very long pages that are difficult to browse through. We could improve this by adding a fixed-positioned table of contents which is automatically generated based on the current page's headings (<h2>, <h3>, etc.).

[abdelouahabb]

Hi,
why the offline version doesent contain the same navigation in the online website?

[Thibaut]

@abdelouahabb Both versions are the same.

[abdelouahabb]

@Thibaut I followed the exact steps, and i dont get the side navigation menu (Chromium and firefox, same result, opensuse)

[Thibaut]

@abdelouahabb can you post a screenshot please

[abdelouahabb]

@Thibaut I updated the comment with screenshot

[Thibaut]

@abdelouahabb and on the same computer / browser, if you load devdocs.io you see the sidebar?

[abdelouahabb]

@Thibaut that's the same, since it is just the dns?

[Thibaut]

Ok so both versions are the same. It's just that you're using a small computer so the mobile version kicks in. What computer / screen resolution are you using?

[abdelouahabb]

@Thibaut i get:

screen.width: 1366
screen.height: 664

[abdelouahabb]

@Thibaut I confirm that it is th css media, i tried to access from windows (because i ran it from virtual machine, on opensuse) and now i get the TOC, thank you ^_^

[Thibaut]

Could you send me the result of these two lines both in your VM and outside:

window.matchMedia('(max-device-height: 767px)').matches

window.matchMedia('(max-device-height: 767px) and (max-device-width: 1024px)').matches

[abdelouahabb]

@Thibaut
Hi, and sorry for the delay, here is the result:

window.matchMedia('(max-device-height: 767px)').matches : true
window.matchMedia('(max-device-height: 767px) and (max-device-width: 1024px)').matches: false

[borekb]

Hi, was this ever implemented? I get ToC on the about page , but nowhere else. Long pages with many headings are quite hard to navigate.

[Thibaut]

@borekb this hasn't been implemented. I felt it's not needed because the sidebar already provides a ToC. On most pages, hitting Alt+R will reveal the current entry in the sidebar surrounded by related entries for that page, which acts as a ToC.

I see how an extra ToC could be useful, though, having added many docs with lots of headings that aren't entries in the sidebar. So I'll reopen this.

[lokesh1729]

Any update on this ?

[lokesh1729]

I believe this is one of the critical features. It improves and unifies the overall reading experience. May I know if there are any blockers ? or it is not possible to add ? The issue had opened 8 years back.

[lokesh1729]

@Thibaut

I felt it's not needed because the sidebar already provides a ToC. On most pages, hitting Alt+R will reveal the current entry in the sidebar surrounded by related entries for that page, which acts as a ToC.

On the sidebar, the entries are the contents for the whole library. Having a ToC for the current page helps a lot. For example, consider this page — https://devdocs.io/django~4.0/topics/auth/default — it is very long, and keeping track of it while reading is hard.

Let me know if it will be implemented or at least point me in a direction on implementing this. We can add this as optional and disable it by default so that users can toggle from the preferences.

[lokesh1729]

Few examples, where there's a sidebar on the left side and ToC on the right side.

https://getbootstrap.com/docs/5.1/getting-started/introduction/

​https://vuejs.org/v2/guide/

​https://docs.spring.io/spring-framework/docs/current/reference/html/core.html

​https://tailwindcss.com/docs/configuration

[brendensoares]

I just poked around the code and I think the file where we would add the table of contents HTML is near the entry page render method.

We would need to find all the headings within content arg and append newly generated HTML that links to each (assuming each heading has a unique id attribute).

[chibby0ne]

This is a big downside of devdocs. Zeal on the other hand does have a table of contents which lists the sections in order whenever you open a page. The desktop application also supports multiple tabs but that's not as important as having a table of contents.
This is a dealbreaker for many people and it's a shame that it's been 10 years (almost to the day) since the issue was open and nothing has been done.

Zeal:

Online devdocs:

Desktop devdocs: