DiscoTOC - automatic table of contents

[Discourse]

	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

As this is an official theme component maintained by the Discourse team, Support, Bug, UX, and Feature requests can be made in the respective categories here on Meta, and tagged with the appropriate theme component tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

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)

• 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

etc...

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:

Settings

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

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

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.

Limitations

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.

Credit

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.

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