Add ability to generate Table of Contents fro Wikis

• Customer / Requester: Big Consumer Electronics Company
• Zendesk ticket: https://gitlab.zendesk.com/agent/tickets/7682

Requested feature

This customer would like to able to generate a Table of Contents for the Wikis that can be displayed on the main wiki page.

Related feedback item: http://feedback.gitlab.com/forums/176466-general/suggestions/4320328-enable-all-the-goodies-in-the-gollum-wiki-engine

Concrete questions / Next steps

@JobV what do you think?

/cc @DouweM

I think this is a nice idea, as we're currently using that feature for doc.gitlab.com. However, we're at the grace of the gollum lib.

If it's possible to do this (@marin?), I think we should. I have a suspicion that if we could've, we already would've though.

If I recall correctly the problem wasn't at Gollum but at Redcarpet and the way GitLab processes markdown since we use same processing for markdown in project and in wiki. Something could have changed recently so it might be worth investigating it closer.

@patricio you can say that we'll try it, but not guarantees or promises.

Milestone changed to 8.2

Assignee removed

Milestone changed to 8.4

@patricio we didn't make this, moved it up.

@JobV thanks for letting me know. I'll update the customer.

Added ~113220 label

Milestone changed to 8.6

Reassigned to @rspeicher

mentioned in commit bc43ad71

mentioned in merge request !2952 (merged)

Status changed to closed by commit bc43ad71

mentioned in commit 3d1de5ba

@patricio I implemented replacing [[_TOC_]] with the Table of Contents for the current page (i.e., each of the Markdown headers), and it will be in 8.6. But it sounded like this customer wants an index of all the wiki pages?

Thanks @rspeicher. A full index, or a sidebar index was in the feedback item from the feedback forum to which the customer referenced. But I believe the way you implemented is a great start.

Hi @rspeicher, great work! Just tested it in 8.6.1 and works nicely! Any plans to include some flags to exclude an entry from the toc (e.g. add <!-- NOTOC --> to a header line to skip it). And any plans to

It would greatly contribute to keeping our wiki organized

@koenlekkerkerker Thanks! No, that isn't something I had considered. Is that a standard thing on other sites? Please feel free to open another issue for the feature proposal.

This is an awesome feature, but I've noticed that the items in the TOC aren't hierarchical. i.e. if you have some H2, or H3's, they all show as H1's in the TOC.

The suggestions for a NOTOC tag is also a good idea for sections you don't want included - as first mentioned by @koenlekkerkerker.

mentioned in issue #19690 (closed)

@alexkb Have the same problem and opened issue #19690 (closed) for it. Feel free to it ;)

Does [[_TOC_]] work for wiki pages only? I tried to use it in README.md but no toc appeared.

@wlnirvana Correct, it currently only works for Wiki pages. This would be supported everywhere (including README.md) when we switch to Kramdown as our Markdown renderer. See https://gitlab.com/gitlab-org/gitlab-ce/issues/18552.

It seems that the TOC generated does take header levels into account, all headers are generated as a straight bullet list

• Header Level 1
• Header Level 2

instead of an indented bulllet list, which is what I would expect.

• Header Level 1
• Header Level 2

@adam-at-epsilon Yup, I also see the missing levels (i.e. a not very useful TOC)

@paulmelis thanks, now I'm not the only one with this issue. Another observation is that bulleted lists only has two levels of indentation:

* lvl one
 * lvl two
  * lvl three

only renders two levels:

• lvl one
• lvl two
• lvl three

which seems to be a bug.

I'm seeing flat TOC from this tag too, on GitLab Community Edition 9.1.3 (2e4e522a).

I don't know if this issue will get seen since its closed, we may need to open another. @rspeicher ?

I use a tool called DocToc that auto generates the markdown table of contents.

However despite the valid markdown gitlab doesn't seem to render the indentation correctly.

I've created #33727 (closed) about the flat TOC