DiscoTOC - automatic table of contents

(Joe) #1

This is a theme component that will allow you to generate an interactive table of contents for your topics with one click!

Repository link

Beginner's guide to using Discourse themes
(open it in a new tab)





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:


This theme only comes with one setting, the toc icon. (used to add the icon to the subset and I don’t recommend changing it.


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.

How do I install this theme component?

Follow the theme installation guide and add the theme component to your active themes.

If you’re new to Discourse themes, you can learn more about them here.


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.


  • live composer preview of toc content (might be too expensive)
  • support for popular themes that alter topic layout
  • clicking links next to headings will copy to clipboard automatically

This is a very early release, if you spot any problems or have ideas for improvement, please let me know.

Automatic Table of Contents generation
Creative Uses of Discourse
Blog Post Styling
Big Header - Little Header
Wiki improvement – Split content into multiple sections?
Deep Linking to Headings (Anchors)
Links not working
(Tobias Eigen) #3

This is sweet! Nice work, and thank you! It looks gorgeous on mobile and desktop, right out of the gate.

I installed this and enabled it out on one of my mega list topics, the FAQ on my forum. See screenshot below and https://community.namati.org/t/faq-frequently-asked-questions-about-the-network-platform/1467.

Some first reactions:

  • it took a few hard refreshes to get the anchor links working properly in my browser. For a while it would just inch its way down the page whatever TOC title I clicked on. It felt buggy, but started working perfectly after a while.
    • so far the links do not work on mobile (ios) but I will try that again later as well. Likely a similar browser issue.
  • the spacing between each title in the table of contents is the same as the spacing between lines for long titles. Could the spacing between lines for long titles be much smaller to help distinguish between them? (see “I am a new member…” in screenshot)
  • it would be nice if the anchor link next to each title only appeared on mouseover or if the color were toned way down so it is less obvious. The current functionality gives the link too much prominence. Most people are not going to care to be able to link to a title.
  • I presume there are good reasons for the markdown method for enabling this feature, but it feels a little clunky and error prone, especially for people new to markdown. Any way to make it function more like whispers, with a toggle and TOC icon displayed next to title in composer when enabled?
  • that said, this is a power feature - any way to limit access to it by trust level? Not display it in the options menu so it can be added via markdown only by power users who know the markdown to use?

(Tobias Eigen) #4

I updated my FAQ to strip out all the html I had put in there to create my manual table of contents. Looks so much better, and it will be so much easier to maintain now with only markdown in the topic. :sunflower:

I do think I discovered a bug. The “hide details” feature does not work on pages with a table of contents. To replicate:

  • create a topic with hide details markdown in it and confirm it works
  • add table of contents markdown and refresh the browser, and confirm it is not working
  • remove table of contents markdown and refresh the browser, and confirm it works again

My FAQ currently demonstrates hide details not working with toc - see moderators section.

(Stephen) #5

This is really awesome, I’ve already mentioned it to a couple of communities and they’re quite excited to try it out.

One safari-specific bug, the ToC is anchored to the top of the post and disappears as you scroll down through it.

A small visual glitch testing this today with with certain window sizes, scrolling below the first post brings the timeline back in, if I then scroll back up slowly I can get the timeline and TOC to overlap.

Can’t screenshot as it’s sensitive content on a private site. Will create a dummy topic to allow me to capture an example later.

(Bank Live) #6

Not sure why it didn’t work as we wanted

This is my issue


(Per Torstensson) #7

Thank you for yet another amazing theme-component @Johani!

I have two installations with which I have tested it with, with the same result – works perfectly in Chrome but have issues in Safari;

  • :white_check_mark: TOC Renders OK
  • :x: Jumps to anchored links on click
  • :x: TOC is sticky on scroll


(Justin René Back) #8

Sadly it produces this error when clicking the Insert button

"Error: Nothing handled the action 'insertDtoc'. If you did handle the action, this error can be caused by returning true from an action handler in a controller, causing the action to bubble.
    at new n (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:4:16439)
    at n.w (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:14:14787)
    at p (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:17:9640)
    at e.trigger (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:18:742)
    at n.send (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:14:20388)
    at n.send (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:15:7485)
    at n.onPopupMenuAction (https://forums.pixelcatproductions.net/assets/application-f8046fe936b726817db0dad513600f2158a8168b0a2346185e49e15b72e3f541.js:17:16948)
    at e._join (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:9:17782)
    at e.join (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:9:14758)
    at u (https://forums.pixelcatproductions.net/assets/ember_jquery-716f4989c2eb49ad65163ffb56185407340c2b195b81b9392b62cde3e992cade.js:4:31643)"

Thank you for this fantastic component, it is a real time saver!

I have converted a few existing topics with manually created ToCs and they are working as expected out of the box, but then I also encountered some issues. I tried to repro them on try.discourse, but the component isn’t enabled there yet.

Issue 1

Multiple headings with the same name produce same #toc-link

  • ToC panel highlights them all but jumps only to the first one

This is a legit scenario:

# first item documentation
## settings
## parameters
### private
# second item documentation
## settings
## parameters
  • Possible solution: create #toc-link from heading text + heading numbering (this would need to be recalculated on each edit)

Issue 2

[link](#toc-link) landing

  • manually inserted link lands roughly one paragraph above actual target
  • link from ToC panel lands correctly (heading at the top)

Issue 3

Manually inserted links [link](#toc-link) aren’t actionable when followed directly by heading

  • not working:
- [link](#toc-link)
- [link](#toc-link)

## heading
  • working:
- [link](#toc-link)
- [link](#toc-link)

some text

## heading

Issue 4

Cannot select heading text or heading link icon

  • this happens with one long heading 2 (50 chars +) but not with the even longer heading 3 (it may be connected to the actual display width rather than number of chars?)
  • this actually happens with two consecutive headings and is similar to issue 3
# Heading One
## heading Two
body text

“Heading One” and its heading link are not selectable.

(Chris Beach) #10

Same here, but I love the concept and execution (bugs aside)

(Tobias Eigen) #11

Actually, an update on this - I just realized that the last link before a new heading does not work on my FAQ with the TOC enabled. It’s not specific to the “hide details” feature.


This theme is baller, really good stuff. :+1:

(Gerhard Schlager) #15

Detail blocks work as long as there is no heading in the details. If there’s is one or more headings inside [details] then it’s impossible to expand the details block and the TOC stops highlighting the current heading when I scroll through the topic.

(B Iggy) #16

Hey and awesome work @Johani :slight_smile:

One issue I have is the offset of the ScrollTo function I guess in combination with my custom header.

My custom header is at the very top and is 70px height.

That 70px is not taken into account as soon as I click on the anchors on the right.

Basically it must have a +70px too and a -70 for the scrollTo function.

I helped myself with hacks for now :wink:


Not sure yet how to detect a custom header :thinking:

(B Iggy) #17

And a bug report:

If you have the first post setup as TOC and users comment on it afterwards and they click on that button to jump to certain posts, the Table of content button is broken (not clickable anymore - I have to reload the page)

(Stephan) #18

Wow, this is really nice. Thanks a lot for this component! :heart:

I immediatly installed it and played around with some topics and had no issues on desktop and mobile.
All looking well and handling is intuitive and easy!

Only one unexpected thing I noticed:

I had a case where headlines contained links which resulted in the toc showing the number of clicks on the link as part of the headline:


(The 27 and 18 in that example screenshot are such link click counts and not part of the headline itself.)

(Germain Metti) #19

I’ve been looking for such a feature for a long time.
This is perfect for my needs!
Thanks a lot. I starred the repo :slight_smile:

(david) #20

A few testers on my forum and myself are currently making a knowledgebase using wiki-posts. This ToC works so well in this scenario; I love it!

(David Kingham) #21

Very nice! It seems to not be working for anon users, try going to this link FAQ - Nature Photographers Network I see the TOC if logged in, but not logged out.

(Tobias Eigen) #22

I cannot repro this on my site. See here where it works for anon and logged in. Maybe there is a prob with the markdown in your post? Or some other plugin or theme component is interfering?

(Justin René Back) #23

Any updates on the issue I had? Spam filter told me it removed it but not quite sure if its back.

Upon pressing the button ember_jquery prints

Nothing handled the action 'insertDtoc'