DiscoTOC - automatic table of contents

:discourse2: Summary DiscoTOC will allow you to generate an interactive table of contents for your topics with one click!
:eyeglasses: Preview Preview on Discourse Theme Creator
:hammer_and_wrench: Repository Link https://github.com/discourse/DiscoTOC
:open_book: New to Discourse Themes? Beginner’s guide to using Discourse Themes

Install this theme component





toc = table of contents

  • Automatically generates the entire toc via a button in the composer gear menu

  • The toc will always be on the screen - scrolls with content like the topic progress widget

  • As you scroll past sections in the topic, the active element in the table of contents will be set to active (blue highlight)

  • adds id attributes to headings (you can link to a specific section from another topic / post)

  • clicking on any link in the toc will instruct the browser to navigate to relevant section (smooth-scrolling)

  • adds a copy-able link next to each heading (if you want to link to it)

  • RTL support

  • The colors are based on your current active color palette

How does it work?

In a nutshell, it looks for headings in topics which are marked to have a toc (via the composer button) and if it turns out the current topic is marked, then it takes all the headings and puts them in the toc (nested in order of heading levels) - this means that your markdown must be syntactically correct.

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6

You’re free to go back and fourth in heading levels, but the order must be correct

# heading 2 
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2


In order for the links in the toc to work, headings must have id attributes. The component will check if the headings already have ids and if they do, then they are respected. This is handy if you ever manually created a toc.

If the headings don’t have ids, then it will generate an id for each heading based on its text (unwanted characters are stripped out)

once all of that is done, it will also add a link next to each button that links directly to that section:


Name Description
minimum trust level to create TOC The minimum trust level a user must have in order to see the TOC button in the composer
composer toc text Text that appears at the top of the preview pane of the composer to indicate the topic will have a table of contents
auto TOC categories Automatically enable TOC on topics in these categories
auto TOC tags Automatically enable TOC on topics with these tags
TOC min heading Minimum number of headings in a topic for the table of contents to be shown


Translation Default
table_of_contents table of contents
insert_table_of_contents Insert table of contents
jump_bottom Jump to end
toggle_toc.show_timeline Timeline
toggle_toc.show_toc Contents

The theme comes with three strings that you can translate or change.

table_of_contents: "table of contents"

this used for the button that opens the toc on mobile

insert_table_of_contents: "Insert table of contents"

this is used as the text for the toc button in the composer gear menu

topic_will_contain_a_table_of_contents: "This topic will contain a table of contents"

This is the text that shows up in the composer preview to indicate that the a toc will be generated for the topic

How do I create a toc?

  1. Write a topic with syntactically correct headings
  2. Click the toc button in the gear menu (only shows up when creating a regular topic - replies and PMs are ignored
  3. Profit.

What happens to the topic progress widget when a topic has a toc?

As you can probably guess, there’s no space to show both at the same time, so the way this component works is as follows

in a topic with a toc, the topic progress widget is hidden while the first post is on screen, and you see the toc instead.

Once you scroll past the first post, the toc will not scroll with you and the topic progress will be shown instead while you read any replies.

So, first posts get the toc, and subsequent posts get the regular topic progress widget.

The happens on both desktop and mobile.

Are there any downsides to using this component?

Nothing I am aware of, all the changes are done on the client-side. So you can easily remove the component and your posts would go back to the way they were before you installed it.


This component assumes the standard topic layout. As such, it won’t work with themes that modify that layout such as the Vincent theme. Support for popular themes that modify the layout will come at a later stage in the form of component settings.


I started with Greg Franko’s tocify.js library. However, it looks like it’s not been updated in a while, so this is essentially a hard-fork that removes a lot of unnecessary features, integrates and styles the rest for Discourse.

So, there are no external requests and the total size is ~ 4kb gzip.

Big thanks to @erlend_sh for lots of valuable feedback and to @david for his help with translations.

:discourse2: Hosted by us? Theme components are available to use on our Standard, Business and Enterprise plans.

Last edited by @JammyDodger 2024-06-12T08:20:05Z

Check documentPerform check on document:

4 posts were split to a new topic: How to move the TOC to the left side of the post?

I don’t know how this component is implemented or much about the frontend structure of Discourse, so I can only throw in a guess.

Couldn’t the progress bar only be shown a) if more than 1 post in the topic and b) adjust its start to be from the 2nd post (instead of 3rd), but also c) add some comfortable bottom/top margin to one of the two elements to make sure the other remains distant enough (eg 1vh) as to not make it strange looking?

In other words, instead of using the whole 2nd post as a gap, use CSS to allow some room between them (iff there’s more than 1 post).

Again, this might not make any sense at all as I don’t know much about the way this is working atm.


Hi there! We recently installed DiscoTOC for our forums and were wondering if it’s possible to get the component to read alt text in images? We’ve used images for some patch note headers…

like so:
Performance and Stability

And unfortunately the TOC system doesn’t seem to be able to parse an image as a header, creating a blank entry on the list and creating a link that takes you to a blank page. Is there any workaround for this beyond “don’t use images”? Thank you! Love the system otherwise.

1 Like

My guess is that the solution is to not use images as headings, but possibly there will be a way to get it to work by adding some code to your site that hooks into the DiscoTOC code. Whether or not it’s worth looking into that will depend on how important it is for you to use images in the post’s headings.


We’ve been using images as headers in our patch notes consistently for quite some time now, and it’s a part of our branding and presentation; not just on the forums, but on Steam and such as well. We would like to have the ability to continue using images as headers while using DiscoTOC in order to remain consistent.

DiscoTOC has been great for other things such as for an AMA recap, a megapost about our dedicated server launcher app, new player guides, etc. We like the system a lot, but would love for a little extra functionality for the way we present patch notes.

1 Like

The heading anchor functionality on this component slightly conflicts with the Automatic header links functionality added in 2.7.0beta6, since headings get two icons on hover, one from Discourse and one from DiscoTOC. Is there a way round this?

1 Like


You can hide the Automatic header links anchor with

.anchor {
  display: none;

Hi dodesz,

I made the post width much larger than the default one, and after install this component it looks something wrong, could you tell me how to fix this problem?

:heart: thanks!

1 Like

On a forum running Discourse 2.8.0.beta4 (90232af778), including the DiscoTOC component leads to an error message:

The component had been activated before and raised an issue with the previously installed Discourse version as well, although I cannot say which version that was.

Are you able to find any error messages related to the issue in your site’s error logs?

That error message is a backend error, while DiscoTOC is a front-end theme-component so it’s hard for those to be related. Do you have any plugins installed?

1 Like

Unfortunately, I couldn’t find anything useful in the /logs.

I do, here’s the relevant excerpt from app.yml:

    - exec:
        cd: $home/plugins
          - git clone https://github.com/discourse/docker_manager.git
          - git clone https://github.com/discourse/discourse-openid-connect.git
          - git clone https://github.com/discourse/discourse-checklist.git
          - git clone https://github.com/discourse/discourse-push-notifications.git
          - git clone https://github.com/discourse/discourse-characters-required.git
          - git clone https://github.com/angusmcleod/discourse-news.git
          - git clone https://github.com/discourse/discourse-data-explorer.git
          - git clone https://github.com/DNOeV/discourse-watch-category.git
          - git clone https://github.com/discourse/discourse-footnote.git
          - git clone https://github.com/discourse/discourse-knowledge-explorer.git

When a header is within a quote, the header doesn’t show up in the TOC. Could this behavior be changed?

This header won’t show up in TOC

Quoted content

This header DOES show up in TOC

Quoted content

I don’t know how it is planned to work but normally no because it’s part of quote, not a heading of that text.

1 Like

Could you try using the html <blockquote> instead? That would allow the header # to be at the start of a line.



### Anchor Header


Anchor Header

I’ve not tried it in a TOC, but it seems to work with the auto-anchor-headers in a regular post.

Why do you want headers within quotes to show up in the TOC? What’s your use case?

Thank you for the idea. It didn’t work for me, though.

Here’s an example of when I use quotes to visually structure content starting under Issue Area: Age


Why are you using quoting like that? Telling source is enough. Plus grammatically that is wrong, in english too.

Is this a bug or just another user, but… how should I close the TOC? I was looking for some basic instructions how an enduser should use private messages and of course I went to new users doc and opened the TOC to see if there is some info.

I was using iPad and DiscourseHub.

I got this:

The TOC is just fine. But it is overlapping text and I coudn’t get is suppress back. So what the heck I did wrong, or didn’t at all :pleading_face: