Automatic Table of Contents generation

(Dave McClure) #1

Has anyone else felt the need more recently to generate tables of contents for a post automatically based on the structure of its headings?

Continuing the discussion from Spec: Table of Contents:

I looked in the linked topic and don’t really see clearly where automatic generation of a table of contents is covered.

I’m documenting some best practices for some communications our org does which currently lean heavily on Google Docs and benefit from Google Docs built-in ToC generation feature.

There may be an opportunity to move these to Discourse in the future, which would provide a number of other benefits (tagging, better discussion, linking between topics, bumping older topics).

Copy/paste from Google Docs to Discourse works so well now, that I anticipate that will also reduce the switching cost. And for this and many other use cases, I’m already starting to find places where suggesting the workflow, “Author you topic in Google Docs, then paste it into Discourse” makes a lot of sense.

But these docs are sometimes lengthy and it may be hard to let go of the easy ToC creation.

13 Likes
Auto Bookmarks plugin
(Jay Pfaffman) #2

I think that few communities create long enough posts that a toc would be useful. This seems like a plugin that quite a few communities could use, though. It would need settings to determine what level of headers should be included in the toc.

2 Likes
(Dave McClure) #3

I think a first pass could just hardcode this. I would look at what Google Docs does as a model. They include H1-H6 in the ToC.

The workflow would be something like:

  1. Write a post with headers
  2. Click a button in the “gear icon dropdown” to generate a ToC
  3. ToC is an outline with links to the headings, indented by heading level
  4. ToC is just markdown inserted into the composer that you can edit/delete
  5. Clicking the “generate ToC” buttons would not replace the existing ToC, but instead, just insert a new one.*

* this is different than what Google Docs does, but probably a lot easier and completely acceptable in my opinion.

6 Likes
Auto Bookmarks plugin
(Jay Pfaffman) #4

A gear task to generate it is a great idea. My concern is that often a toc is just annoying.

If you’ve got a budget, post in #marketplace. This seems like a great idea.

0 Likes
(Dave McClure) #5

I agree. I wouldn’t want these showing up in every post without some explicit action.

Sorry, I don’t, beyond what our org currently pays Discourse annually for enterprise hosting.

But I’ll also just continue to participate here as a normal user, hopefully sharing a worthwhile perspective that can help the community gain insights into what things may be valuable to add to the product independently.

4 Likes
(Jay Pfaffman) #6

Ah! I hadn’t realized that they were hosting you.

0 Likes
(Tobias Eigen) #7

This is an interesting approach and I like it! If this functionality were made available we would certainly use it in my community. The [toc] short code is one of the few things I miss from drupal.

I am in the process of moving our operating procedures into wikis in discourse and it’s working quite well. The workaround to no automatic table of contents is to use the details markdown, which lets me tidily display a series of steps and lots of structured information without making the post so long it takes loads of scrolling to get to what you need. I also put some stuff in the second and third post in a topic to separate it for easy access.

(Maybe this topic needs a more detailed title to distinguish it from the other one, or they can be merged?)

7 Likes
#8

Generating a ToC made up of all the Categories (which are hyperlinks) would be really nice for a welcome post!

0 Likes
(Ted Strauss) #9

Would really like to have this feature in Discourse.

@tobiaseigen was something developed to generate the ToC in this post? Oh I guess not (after re-reading the post).

There are ruby libraries that seem to have the feature built in, to parse markdown and generate a ToC:

2 Likes
(Tobias Eigen) #10

Nope - I wrote that ToC manually, sadly… If you look at the raw markdown you can copy the syntax I used.

2 Likes
(Sam Saffron) #11

For the record, I like this suggestion a lot and am kind of warm to having it as a core plugin.

[toc][/toc]

### I am the first heading

## I am the second big heading

and so on...

This does not come up A LOT, however would be very useful for posts such as: Official Single-Sign-On for Discourse (sso) and other large wikis.

20 Likes
#12

On reflection, I’d love this more. Just adapted the Discourse New User Guide for one of my own sites and manually having to edit all the links was a pain (but of course I appreciated the head start) and there’s a potential for mistakes.

5 Likes
(Joe) #13

There’s now a theme component to automatically generate a table of contents.

18 Likes