DiscoTOC - automatic table of contents | theme component request

Hi all! I’m coming to you today with a feature request that could greatly improve how we use this forum. DiscoTOC is a theme component that allows you to generate an interactive table of contents for your topics with one click!

An example of this theme component can be found here.

Here is the repository link.

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
  • As you scroll past sections in the topic, the active element in the toc will be highlighted blue
  • 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 the relevant section (smooth-scrolling)
  • Adds a copyable link next to each heading (optional)

The latter three features (highlighted in gray) are already available to us through HTML Heading IDs. However, DiscoTOC would make the creation of tables of contents more accessible to the general user.

How does it work?

DiscoTOC (when enabled via the composer button) takes all headings and puts them in a table of contents, nested in order of heading levels.

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6

You can go back and fourth between heading levels, but the order must be progressive, as shown below:

# 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. DiscoTOC will check if the headings already have ids and if they do, then they are respected. This is great 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.

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 topic - replies and PMs are excluded)

f6a17663a6fa3c4b0bfd6ddc8564a0a58441445e
Credit to Joe

What happens to the topic progress widget when a topic has a toc?

In a topic with a toc, the topic progress widget is hidden while the first post is on screen, allowing you to 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.

Credit

6 Likes

I am not sure if this community can be integrated with theme components, as it is hosted by discourse (paid plan).

2 Likes

On discourse’s website, when it comes to paid plans, discourse offers a variety of plugins for free. The customers are guided here:


I think that in order to add a plugin on a community hosted by discourse, it should be under the #plugins category with the tag #official.

1 Like

I see now—this forum is hosted on Discourse’s servers, meaning Infinite Flight doesn’t have full control over the software. I was under the impression that theme components could be used by anyone.

1 Like

Only plugins are restricted on Discourse hosted sites depending on what plan you have. Theme components can be installed at any time

1 Like

Right, that’s what I thought. I’ll do some more research into the matter. In the meantime, if any staff member would like to clarify, that would be great.

All they need to do is go to admin -> customise -> theme components and then get the Github repository and install the component. This works on a Discourse hosted site I am admin on.

1 Like

I asked on the Discourse meta and was told that theme components can be installed by those that are hosted by Discourse on a paid plan.


This user is on the standard plan and has DiscoTOC installed:

There are a number of add ons that we could use. However, because we are hosted by discourse we are limited to what can be applied both in terms of options and cost. Some items have to be install d and supported by discourse which may have a cost involved.

3 Likes

I don’t believe this theme component costs anything extra and it’s fairly simple to install.


To install a theme component:

  • Via the UI head to Admin > Customize > Themes

  • Click “Components”

  • Click “Install”

  • Click “From a gitHub repository”

  • Enter: https://github.com/discourse/DiscoTOC


From there, the component can be added to our active themes (light & dark) using the “Include component on these themes” setting.

Voila! A free and easy-to-use feature that would greatly improve formatting and organization on this forum!

Thanks for this but staff will evaluate what to install.

Of course, I was just trying to explain that themes and theme components can always be installed by a forum administrator. There are no restrictions on that, whether one is hosted by Discourse or not.

You may have been thinking of plugins here. The server admin (in our case Discourse) is the only one that can install plugins and some are not possible on different hosted plans.

The point I was trying to make is that we are hosted by discourse and pay money to them and you do not know what they do and do not support. Thank you for the suggestion but staff will apply what they think is best.

1 Like