 |
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)
-
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?
- Write a topic with syntactically correct headings
- Click the toc button in the gear menu (only shows up when creating a regular topic - replies and PMs are ignored
- 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.
thanks!
