Creating a Table of Contents

Hi friends :wave:,
I have added a new plug-in that enables creating an automatic table of contents (toc) for users starting with trust level 1. It is a great feature created by Discourse, that lets you now finally structure long posts with ease!

[The following text is work by Joe from the Discourse team]:


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:

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.


I hope you enjoy the new feature! If you encounter issues with it, please let me know in the #forum-feedback section :slight_smile: .
Happy writing!

1 Like