DiscoTOC - automatic table of contents

Thanks @topological :slight_smile: I’ve moved your bug report over to the DisoTOC topic itself to hopefully get it in front of the right people. :+1:


Thanks for the report and the PR. As noted in the PR, I have implemented a different fix, that doesn’t rely on headings having anchors as children.

(I’m happy to merge the translations in your PR, though.)


First off, this is a super helpful theme component for long posts!

However, there’s an issue with this theme component on mobile devices (at least on iOS). When I open a large table of contents, scrolling through the TOC doesn’t work on mobile like it does on a desktop.

The list contains Headings A-H, but I can’t scroll through it

The list appears to be scrollable, but a touchstart event prevents the list from being scrolled. Disabling the touch start event listener for the d-toc element seems to solve the issue.

I can’t see the version of the theme component we have on our forum, nor can I test this on a local install (since I can’t load it on a phone). So, if there is a fix I’m not aware of or if there’s anything I should, please let me know.

Thanks in advance :slight_smile:


Thanks for the report, the screenshots were particularly helpful in tracking down the issue. This is a problem that comes from core, one of the parent elements of the DiscoTOC mobile UI disables scrolling of its children, and this affected DiscoTOC. Should be fixed via FIX: Limit pan event handler to fix scrolling in TOC by pmusaraj · Pull Request #16673 · discourse/discourse · GitHub (it’ll likely be merged early next week).


Is this still working?

@pmusaraj I guess it’s possible that I haven’t set this correctly but I have installed the theme and the TOC I set up on a topic is not appearing on the discourse-docs version but it is appearing in the main topic


Hmm, I agree, the ToC seems not to be appearing in discourse-docs pages again. For example:



The mobile scrolling issue fix is now merged. I also added a compatibility fix for the discourse Docs view, you can see it in action here on meta.


If you prefer to have the table of content always fully expanded, try adding this CSS to your theme

#d-toc li.d-toc-item > ul {
  max-height: 500em !important;
  overflow: visible !important;
  opacity: 1 !important;

Can confirm that’s been fixed as well :+1:


I might be missing something obvious (as it happens often). When I add a TOC I lose access to the top right wrench menu, so I cannot pin/unpin a topic (using for some long event pages).

So the only way to change is to temporarily remove the TOC to access the button.?

With Disco:

Without Disco:


Yes, this is by design. In this case you can use the wrench on the topic menu, at the bottom.


My wrench menus are different. The right side one at top right (which disappears with DiscoTOC) shows:

and my bottom topic one:

So I have no access to the Pin topic settings there (unless I am looking at wrong wrench)

1 Like

Yes, you are looking at the wrong wrench. :wink: The second screenshot you provided is of the post admin wrench, at the bottom of every post. There is another admin wrench in the topic menu at the very bottom, before suggested topics.


Oi! I had the wrong wrench. Now I got it, many apologies, all is good


I seem to be missing the anchor links next to the headings, which allowed me to link to a specific section directly, for instance in this topic, like described in the start post:

Is this me or did this functionality disappear?


They should be there? I’m currently on my phone, but I grabbed this one by long-pressing on the gap to the side of the heading:



Yes, that topic has those anchor links, but that’s a topic that does not have the DiscoTOC.

But this topic has a TOC and does not have anchors: Beginner's guide to using Discourse Themes and this one does not have anchors either DiscourseConnect - Official Single-Sign-On for Discourse (sso)

EDIT Hmm…this topic does have anchors: Discourse API Documentation


Ah, I can explain. The topic you linked has html headings (<h3>, <h4> and so on) and initially the TOC component had its own logic for adding heading anchors. However, since then, core added automatic anchors and recently I removed the custom anchor login in the theme component. However, core’s anchor feature only works for Markdown headings (using ###).

So that’s the OP here has anchors, but the linked guide doesn’t.

We probably should update that guide to use Markdown instead of HTML @JammyDodger.


Ah! That explains things perfectly, thanks Penar!!


I was clearly not paying enough attention yesterday. :slight_smile: I have now swopped in Markdown headers for the two example topics. :+1: