### 作者：  [@Tom\_Newsom](https://meta.discourse.org/u/Tom_Newsom)
#### 发布日期： [2015 年8 月 18 日 13:46 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/1 "2015-08-18T13:46:42Z")
Continuing the discussion from [Is there markdown for creating a table of contents in a topic?](https://meta.discourse.org/t/is-there-markdown-for-creating-a-table-of-contents-in-a-topic/15918/10):
> [@tobiaseigen](#):
>
> Even more lovely would be to be able to add `[toc]` in a post to automatically generate this list of links to headers within the post.
Ok, I’d really like to see this happen, so here’s my attempt at making a spec for it.
> This feature allows the automatic creation of a table of contents for any post (although it’s best suited to Wiki posts).
## Details
- To invoke the feature, add the `[contents]` markup to a post.
- After cooking the markdown, the code scans the post _below_ the `[contents]` markup and adds an anchor before each Header element (this allows for a preamble or top-level title to be excluded from the contents).
- The text and anchor of those Header elements are then composed into a `` and inserted at the location of the `[contents]` markup.
- Each sub-list should be indented by relative hierarchy, not Header size. This allows for “jumps” in Header size to produce a tidily indented list.
- List item styling, however, _is_ applied based on the Header level it refers to.
Examples with the list item styles **H1** _H2_ and H3:
**H1**
_H2_
_H2_
_H2_
**H1**
H3
H3
H3
_H2_
H3
H3
H3
**H1**
H3
H3
_H2_
H3
H3
**H1**
_H2_
H3
H3
_H2_
H3
H3
## Options
`[contents min=1 max=3]`
where min and max are the limits of H elements to index. I suppose it should support up to H6 given that those can be generated with HTML. 1 and 3 are the default if left unspecified.
I toyed with a style= parameter for bullets or numbers, but I think numbers will be misleading because the contents of the post are subject to change, making the numbering inconsistent over time.
## Example output
Pay close attention to the numbers!
```plaintext
```
Where “h1- **3** ” is the anchor of the **third** H1 element in the topic etc.
I suppose you could generate random strings if you want to reduce the chances of clashing with a user-generated Anchor somewhere else in the post.
## ##Mockup
This post: [Laser Cutter - Trotec Speedy 300 (60W) - Tools - Discourse – South London Makerspace](https://discourse.southlondonmakerspace.org/t/laser-cutter-trotec-speedy-300/14)
Makes his sort of thing, only prettier because I’m just slapping this together in Paint. If I have time later, I might do a more carefully designed mockup.
##Thoughts
It takes up a lot of vertical space. Maybe it could be pushed into one of the gutters at wider window sizes? Or even float over the gutter as you scroll, so you can always access it from all points in the post?
---
### 作者：  [@fefrei](https://meta.discourse.org/u/fefrei)
#### 发布日期： [2015 年8 月 18 日 14:12 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/2 "2015-08-18T14:12:13Z")
For readability, I’d not call the anchors `1-1` and so on, but generate a URL-compatible slug just as for topics.
This would result in nice URLs like `https://meta.discourse.org/t/spec-table-of-contents/32248#details`. 😃
---
### 作者：  [@Tom\_Newsom](https://meta.discourse.org/u/Tom_Newsom)
#### 发布日期： [2015 年8 月 18 日 14:14 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/3 "2015-08-18T14:14:49Z")
The danger comes when you have identically titled sub-headers in different locations.
Whatever method is chosen, you have to guarantee unique anchor URLs.
EDIT: oh and what if multiple posts in a topic have a Contents?
---
### 作者：  [@fefrei](https://meta.discourse.org/u/fefrei)
#### 发布日期： [2015 年8 月 18 日 14:18 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/4 "2015-08-18T14:18:11Z")
Good point, this could clash. Some ideas:
- Always concatenate all higher-level headings, like in `#about-details`?
- Check for clashes and append a number?
- Use both your number and a slug, e.g. `https://meta.discourse.org/t/spec-table-of-contents/32248#1-1-details`?
* * *
Supporting multiple posts in a topic having contents is awful if you want to guarantee clash-freeness, because it means that a post cannot be baked without knowing about the other posts in the same topic. My only (awful) idea to avoid this would be to also add the post number to the anchor.
---
### 作者：  [@Tom\_Newsom](https://meta.discourse.org/u/Tom_Newsom)
#### 发布日期： [2015 年8 月 18 日 14:25 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/5 "2015-08-18T14:25:28Z")
> [@fefrei](#):
>
> My only (awful) idea to avoid this would be to also add the post number to the anchor.
Not so awful IMO.
`https://meta.discourse.org/t/spec-table-of-contents/322481#1-H1-1-details`
Yeah it’s full of numbers, but it begins and ends with the human-readable bits.
---
### 作者：  [@gerhard](https://meta.discourse.org/u/gerhard)
#### 发布日期： [2015 年8 月 18 日 14:30 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/6 "2015-08-18T14:30:29Z")
HTML anchor support should be part of the 1.4 release. I’d say let the team worry about solving those problems. 😉
> [@Discourse Version 1.4](https://meta.discourse.org/t/discourse-version-1-4/26488/1):
>
> HTML anchor support that works for deep linking to headings in a post
---
### 作者：  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### 发布日期： [2015 年8 月 18 日 21:00 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/7 "2015-08-18T21:00:55Z")
It’s possible this will get pushed to a future release, though.
---
### 作者：  [@HAWK](https://meta.discourse.org/u/HAWK)
#### 发布日期： [2015 年8 月 18 日 22:45 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/8 "2015-08-18T22:45:06Z")
Adding for posterity that this is something that we’d also love. We’re having to use a separate wiki platform in the mean time to get around the current lack of TOC functionality.
---
### 作者：  [@tobiaseigen](https://meta.discourse.org/u/tobiaseigen)
#### 发布日期： [2015 年8 月 19 日 00:41 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/9 "2015-08-19T00:41:26Z")
I created a TOC manually recently for a FAQ on my discourse - it’s fairly time consuming to create but looks awesome!
[http://community.namati.org/t/common-questions-about-using-the-network-platform/1467?u=tobiaseigen](http://community.namati.org/t/common-questions-about-using-the-network-platform/1467?u=tobiaseigen)
This would have saved me some time if the TOC were generated automagically, but today I am not sure it’s really so important for a discussion platform, esp as long as wiki topics lack other essential wiki functionality anyway. Like @HAWK we’ve moved our wiki content elsewhere. But perhaps that’s a topic for another day.
All that said if this is developed I like this @Tom_Newsom idea for naming anchors and would love to see it implemented this way.
> [@Tom\_Newsom](#):
>
> Not so awful IMO.
>
> [https://meta.discourse.org/t/spec-table-of-contents/322481#1-H1-1-details](https://meta.discourse.org/t/spec-table-of-contents/322481#1-H1-1-details)
>
> Yeah it’s full of numbers, but it begins and ends with the human-readable bits.
---
### 作者：  [@Reno](https://meta.discourse.org/u/Reno)
#### 发布日期： [2015 年9 月 23 日 20:20 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/10 "2015-09-23T20:20:26Z")
Automated TOC, is a most requested feature for many of our users.
It would be great to have this implemented as we try to get away from the old conventional wikis
Thanks!
---
### 作者：  [@tobiaseigen](https://meta.discourse.org/u/tobiaseigen)
#### 发布日期： [2015 年11 月 10 日 22:11 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/11 "2015-11-10T22:11:05Z")
This just came up on my site again - we have a program update that is sent out once every few months via a discourse topic and it gets quite long. Having the ability to add a `[toc]` shortcode at the top and have it automagically generate a table of contents at the top of the post is thus an important priority again.
---
### 作者：  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### 发布日期： [2016 年8 月 4 日 20:44 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/12 "2016-08-04T20:44:19Z")
We do have heading anchor link support in 1.6 now.
> [@Linking to a heading within a post or topic](https://meta.discourse.org/t/deep-linking-to-headings-anchors/47552):
>
> bookmark This guide explains how to link directly to a heading within a Discourse post or topic, enabling users to navigate long posts efficiently. person_raising_hand Required user level: All users Adding headings within long posts can make the content more readable and allow users to link directly to specific sections. This can be particularly useful for navigating extensive discussions and documentation. Summary This guide covers: Creating headings using Markdown Linking directly …
---
### 作者：  [@alefattorini](https://meta.discourse.org/u/alefattorini)
#### 发布日期： [2016 年8 月 29 日 13:13 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/13 "2016-08-29T13:13:43Z")
Can we automatically create a TOC easily now? Or do we have to do it manually?
---
### 作者：  [@jomaxro](https://meta.discourse.org/u/jomaxro)
#### 发布日期： [2016 年8 月 30 日 00:09 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/14 "2016-08-30T00:09:26Z")
I haven’t found a way to do it automatically yet, but I would love to be able to do so! We’re using Discourse at my work as a knowledge base, and certain articles are very long it would be great to have this generated (like MediaWiki does).
---
### 作者：  [@alefattorini](https://meta.discourse.org/u/alefattorini)
#### 发布日期： [2016 年8 月 30 日 07:40 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/15 "2016-08-30T07:40:35Z")
TOC is one of the mandatory features useful to use Discourse as a wiki. I don’t need fancy things 🙂
---
### 作者：  [@erlend\_sh](https://meta.discourse.org/u/erlend_sh)
#### 发布日期： [2016 年8 月 30 日 10:58 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/16 "2016-08-30T10:58:31Z")
> [@alefattorini](#):
>
> Can we automatically create a TOC easily now?
Automatic TOC generation is a difficult problem to solve. There’s more discussion about this in the aforementioned feature topic:
> [@Linking to a heading within a post or topic](https://meta.discourse.org/t/deep-linking-to-headings-anchors/47552):
>
> bookmark This guide explains how to link directly to a heading within a Discourse post or topic, enabling users to navigate long posts efficiently. person_raising_hand Required user level: All users Adding headings within long posts can make the content more readable and allow users to link directly to specific sections. This can be particularly useful for navigating extensive discussions and documentation. Summary This guide covers: Creating headings using Markdown Linking directly …
---
### 作者：  [@erlend\_sh](https://meta.discourse.org/u/erlend_sh)
#### 发布日期： [2016 年8 月 30 日 10:58 UTC](https://meta.discourse.org/t/spec-table-of-contents/32248/17 "2016-08-30T10:58:35Z")