DiscoTOC - automatic table of contents

Hi, I face the following issue.
If there are chinese headings, TOC link can not link to correct location.
For example, KeepZotero 防止 Zotero 被關掉 - 綜合討論 - TW Community
Clicking the 2nd-5th links from right side table always shift to second heading position not the corresponding position.
If click the link on heading left side, it works and the link is like ${topic-url}#h-4
Is it the same issue as Bug of DiscoTOC with Chinese Headings - bug - Discourse Meta mentioned?


I believe it is the same


I try your fix on my site and it works correctly.
Do you plan to create a pull request?


I am using DiscoTOC for a long time, and it works fine with Chinese headings until recent update.

If there are multiple Chinese headings (including no ascii characters) in the post, it will only navigate to the first heading of one level when the navigation item on the right side is clicked. I believe this is because the DiscoTOC generates navigation items with the same id (because the headings are all in Chinese). So, the query selector will only find the first heading.

As a try, I forked the GitHub repo and pushed a little commit as

It seems to work in my site. If it looks good to you team, I can raise a pull request, or this bug need to be fixed in another way.


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:


5 posts were split to a new topic: When ToC present, I lose access to the topic wrench?

Nice component, the # links created for the headings are very neat too.

Is there a way to move the icon link as pictured in the screenshot?

Right now it hovers over the left, in between the user icon and heading text (see below)

Screen Shot 2022-07-13 at 7.27.19 PM


A suggestion if I may.

By nature, posts with TOC will be long. When the Google crawler sees the page it doesn’t see the TOC nor those nifty links to different parts of the page. Perhaps on the crawler version we can have those links show up for each heading/sub-heading.

1 Like

What is the purpose of the anchor icon setting?
I could not find it anywhere. Was it removed in REFACTOR: General component overhaul (#19) · discourse/DiscoTOC@20366c6 · GitHub ?

1 Like

Awesome component! However I’ve found a bug in how it parses and renders TOC’s which contain escaped and certain characters.

For example it doesn’t render these headers correctly

### <a name="profilename">**[\<Profile Name\>]**</a>
### [\<Profile Name\>]
### \<encoder\>-general=\<general parameters\>

You can try my fix XD

As a non-latin language speaker, this theme component was not working well on my forum until I made some changes in javascripts/discourse/initializers/disco-toc-main.js

 headings.forEach((h, index) => {
              // suffix uses index for non-Latin languages
 ---             const suffix = slugify(h.textContent) || index;
 +++             const suffix = /*slugify(h.textContent) ||*/ index + "-salt-" + Math.round(Math.random() * 1145141919);
              const id =
                h.getAttribute("id") || slugify(`toc-${h.nodeName}-${suffix}`);

I used a huge random number instead of a title slug to make the link; it works fine in non-latin texts.

As you can see, it’s harder to get two titles confused than to win the lottery XD.

1 Like

2 posts were split to a new topic: Using DiscoTOC on published pages

6 posts were split to a new topic: DiscoTOC not showing in composer after latest component update