 |
Summary | DiscoTOC will allow you to generate an interactive table of contents for your topics with one click! |
 |
Preview | Preview on Discourse Theme Creator |
 |
Repository Link | https://github.com/discourse/DiscoTOC |
 |
New to Discourse Themes? | Beginner’s guide to using Discourse Themes |
Install this theme component
Samples
Desktop
Mobile
Features
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)
-
Each toc entry links to the heading’s anchor, so you can also link to a specific section from another topic or post
-
Clicking on any link in the toc will instruct the browser to navigate to the relevant section (smooth-scrolling)
-
In topics with replies, a Contents / Timeline button lets readers switch between the toc and the normal topic timeline. The choice is remembered in the browser
-
Works with the Discourse Docs plugin
-
Optional support for tocs in replies, not just the first post
-
RTL support
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
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
etc...
A few things to know about which headings are compatible
-
h1throughh5are included.h6is not - Headings inside quotes are ignored, so quotes won’t pollute the toc
- The toc only appears if the post has at least as many headings as the TOC min heading setting (3 by default)
How do the links in the toc work?
Every heading in a cooked post gets an anchor in the form p-<post id>-<heading slug>-<number> — it’s the target behind the a heading. DiscoTOC links to those anchors rather than inventing its own.
Because those anchors include the heading’s position in the post, they change if you reorder or retitle headings. If you’re linking to sections from elsewhere, you can add stable named anchors above the heading:
<div><a name="my-section"></a></div>
## My section
Then link to /t/your-topic-slug/1234#my-section. Discourse allows <a name="..."> in posts. DiscoTOC’s own entries will still use the core heading anchors, but yours will continue working regardless of edits.
Settings
| Name | Description |
|---|---|
| minimum trust level to create TOC | The must have in order to see the TOC button in the composer |
| composer toc text | Text that appears at of the composer to indicate the topic will have a table of contents |
| auto TOC categories | Automatically enable categories |
| auto TOC tags | Automatically enable TOC on topics with these tags |
| enable TOC for replies | Allows TOC for replies. TOCs for replies are not affected by the auto TOC tags and auto TOC categories settings and must be inserted manually |
| TOC min heading | Minimum number of headings in a topic for the table of contents to be shown |
composer toc text is what shows up in the composer preview to indicate that a toc will be generated:
Translations
| 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 |
table_of_contents: "table of contents"
this is 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
toggle_toc.show_toc: "Contents"
toggle_toc.show_timeline: "Timeline"
these label the button that switches between the table of contents and the topic timeline
How do I create a toc?
- Write a topic with syntactically correct headings
- Click the toc button in the composer gear menu. By default it only appears on the first post of a topic; enable the enable TOC for replies setting to use it in replies as well
- Profit.
What happens to the topic progress widget when a topic has a toc?
There’s no space to show both at the same time, so in a topic with a toc the topic progress widget is hidden while you’re on the first post, and you see the toc instead. Once you scroll past the first post, the toc is replaced by the regular topic progress widget while you read replies. (With enable TOC for replies on, a reply that has its own toc shows that one instead.)
In topics with more than one post, a Contents / Timeline button lets readers switch between the two, and the preference is remembered in their browser.
On narrow screens the toc opens as an overlay via a button in the topic progress area.
Are there any downsides to using this component?
Almost everything happens client-side, so you can remove the component at any time and your posts will render as they did before. The one thing that touches your content is the composer button: it wraps the post in a <div data-theme-toc="true"> marker, which is how the component knows the post should have a toc. If you uninstall the component, that wrapper stays in the post but has no visible effect.
Limitations
h6 headings and headings inside quotes are not included in the toc.
Credit
This started as a hard fork of Greg Franko’s tocify.js library, and has since been rewritten as native Ember components. There are no external dependencies or requests.
Big thanks to @erlend_sh for lots of valuable feedback and to @david for his help with translations.
Last edited by @awesomerobot 2026-07-27T16:04:08Z
Check document
Perform check on document:
thanks!
