Skip to content

GLFM renders a TOC not only when used on its own line

Implementation guide

Using [[_TOC_]] seems to work correctly. It must be one a line by itself and is not detected inside inline code.

However

[toc]

seems to be detected inside inline code, whether it's inside a sentence or not. For example, putting the following markdown in a description will generate a table of contents when it shouldn't.

## TOC Test

This is a sentence `[toc]`

We want it to behave just like the [[_TOC_]] syntax. The fix will most likely need to be in https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/table_of_contents_tag_filter.rb with tests added to https://gitlab.com/gitlab-org/gitlab/blob/master/spec/lib/banzai/filter/table_of_contents_tag_filter_spec.rb

Once that is fixed, we can also fix https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#L1328-L1341 which had to work around this bug.

Summary

The documentation for GLFM TOCs states:

A table of contents is an unordered list that links to subheadings in the document.
You can add a table of contents to issues and merge requests, but you can't add one
to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line
to the **Description** field of any of the supported content types:

And this is rendered in GitLab (and most likely, in self-managed docs) as:

image

Either:

  • The TOC should not generate when [TOC] is used in a sentence, or when it's in backtics.
  • The docs need to be updated to reflect this state and improve readability of this topic.

Steps to reproduce

Example Project

What is the current bug behavior?

What is the expected correct behavior?

Relevant logs and/or screenshots

Output of checks

Results of GitLab environment info

Expand for output related to GitLab environment info 

(For installations with omnibus-gitlab package run and paste the output of:
`sudo gitlab-rake gitlab:env:info`)

(For installations from source run and paste the output of:
`sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production`)

Results of GitLab application Check

Expand for output related to the GitLab application check 
(For installations with omnibus-gitlab package run and paste the output of:
sudo gitlab-rake gitlab:check SANITIZE=true)


(For installations from source run and paste the output of:
sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production SANITIZE=true)


(we will only investigate if the tests are passing)

Possible fixes

Edited by Brett Walker