The Table of Contents macro scans the headings on the current Confluence page to create a table of contents based on those headings. This helps readers find their way around lengthy pages, by summarising the content structure and providing links to headings.

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Macro parameters

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Sets the indent for a list according to CSS quantities. Entering 10px will successively indent heading groups by 10px. For example, level 1 headings will be indented 10px and level 2 headings will be indented an additional 10px.

Separator(separator)

brackets

This parameter applies to flat lists only. You can enter any of the following values:

brackets — Each item is enclosed by square brackets: [ ].

braces — Each item is enclosed by braces: { }.

parens — Each item is enclosed by parentheses: ( ).

pipe — Each item is separated by a pipe:

anything — Each item is separated by the value you enter. You can enter any text as a separator, for example "***". If using a custom separator, be aware that text displays exactly as entered, with no additional white space to further separate the characters.

Minimum Heading Level(minLevel)

1

Select the highest heading level to start your TOC list. For example, entering 2 will include levels 2, and lower, headings, but will not include level 1 headings.

Maximum Heading Level(maxLevel)

7

Select the lowest heading level to include. For example, entering 2 will include levels 1 and 2, but will not include level 3 headings and below.

Include Headings(include)

Filter headings to include according to specific criteria. You can use wildcard characters. See Sun's Regex documentation for examples of constructing regular expression strings.

Exclude Headings(exclude)

Filter headings to enclude according to specific criteria. You can use wildcard characters. See Sun's Regex documentation for examples of constructing regular expression strings.

Printable(printable)

checked

By default, the TOC is set to print. If you clear the check box, the TOC will not be visible when you print the page.

CSS Class Name(class)

If you have custom TOC styles in your CSS style sheet, use this parameter to output the TOC inside <div> tags with the specified class attribute.

Absolute URL(absoluteURL)

By default, the links in the TOC are relative URLs pointing to the current page. If checked, the links in the TOC will be full URLs. This setting is useful when you are including a page with a Table of Contents in another page, and want to control where the links should take the user.

Examples

The examples below are based on this table of contents:

Filtered Table of Contents

This example filters the headings to include those that contain 'Favourite', but excludes headings which end with 'Things'. The list is styled with Roman numerals.

Parameter

Value

List Style

upper-roman

Include Headings

Favourite.*

Exclude Headings

.*Things

The resulting table of contents is:

Flat List

This example filters all headings to render a flat list of 'Unknowns' enclosed in square brackets (the default list style).

Parameter

Value

Output Type

flat

Maximum Heading Level

2

Include Headings

Unknown.*

The resulting table of contents is:

Notes

When you use a Table of Contents macro in a template, you will see an error when you preview the template itself. But the Table of Contents macro works on the pages that people create from the template – the table of contents shows up after they have saved the page. (This is probably because the template is not defined as a page, and the Table of Contents macro works for pages only.)

Due to an outstanding issue in the Table of Contents macro (CONF-10619), the macro browser's Refresh function does not render any parameter modifications. Currently, the rendering of parameter value modifications to the Table of Contents macro occurs only after the page is saved.

Using HTML heading markup with the Table of Contents macroThe Table of Contents macro cannot handle HTML heading markup on its own. Hence, if you use the HTML and HTML Include macros to render HTML heading markup in a Confluence page, the Table of Contents macro will not create a contents list out of these headings. (For more information about this issue, please refer to TOC-93.)However, if you insert an HTML anchor into each HTML heading on your page (based on the following syntax), the Table of Contents macro will incorporate these headings into your contents list.

The syntax for the anchor name is the page name and heading name separated by a hyphen. Remove all spaces and convert all text to lower case. Convert all punctuation marks to their URL-encoded equivalent.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page.

Anonymous

Anonymous

Hello. I'm looking for a way to render a table of contents so that the headings collapse. In other words, something like the {pagetree} macro, but rather than dealing with pages, it deals with headings in single document. Ideally I'd like to see some sort of expand collapse feature for {toc}.

Am I missing something? Also looks like they just update confluence to the latest ver and now I can't edit my document in the wiki Markup mode directly. I need to do it in rich text editor mode and go to Insert -> Wiki Markup to insert...

I use the {toc} macro to build a table of contents that includes headings for included pages. To do this, I use the includePages parameter. There does not seem to be any documentation on the Confluence site about this parameter; I found information at Adaptavist.

Is this a deprecated feature? If not, would it be possible to update the documentation to include the definition and some examples?

Anonymous

When exporting to PDF, I would like the headings of "page 1" and its children to be numbered as listet in the toc. Unfortunately I do not know how to do this.

Second, it would be nice, if home was not numbered and the counting would start with page 1, since home seems to be the only parent page possible. This is quite unfortunate since my wiki must me exported to PDF as an support manual.

I am using the TOC macro to create an index to information imported to a page via the metadate-report macro. The metadate-report is in a column on the left and the toc is in a column to the right. All works fine except that the toc does not show any new headings that have shown up since the last time the page with the toc was edited and saved. The new items show up in the metadata but the list in the toc does seem to get updated. It seems that the content of the toc is generated when the page is saved and does not refresh each time the page is displayed.

Anonymous

I have an issue with the TOC macro and Firefox. If the heading contains a comma (,) or brackets (()) or any number of other "special" characters, the anchors the macro creates replaces those characters with entities.

For example,

ITSM (IT Service Management)

Creates the anchor

ITSM%28ITServiceManagement%29

The link works fine in IE and Chrome, but Firefox changes the %28 and %29 back to ( and ), which doesn't match the anchor and so the link fails.

Firefox is the browser of choice for most of the people where I work, and it is frustrating for so many links to fail.

It would be great if there was a parameter for the TOC macro that would cause "special characters" to be ignored when the anchor is created.

Anonymous

Hi All,

I have quick question... I have a doc that looks like this:

The TOC macro doesn't seem to properly handle the nesting of repetitive subsection names. Any of the "Success" entries will always point to the the first one in the doc? Anyone have a workaround/suggestion other than renaming the sub headers?

Using the wiki markup to modify / differentiate the headers doesn't appear to work anymore. I'm guessing it is because the wiki markup is translated into whatever is really stored, and what is really stored is no longer different. The workaround I'm using is to add spaces to the end of the header, but this does not look great in the TOC

Anonymous

There seems to be a bug in the TOC macro when users change the color of a header. The TOC generates, but the TOC linking does not work properly. Has anyone had success creating a TOC out of colorized headers? If the headers use the default color, the TOC works fine.

We have a couple users that have used the TOC macro on their pages and generated emails based on the page. In those emails, the link to pages work, but the TOC links, being relative, do not seem to behave properly. Users that click on the TOC links are taken to the Dashboard instead of the page. It appears that the TOC links in the emails are being sent to http://server.name/contextroot/#relativeTOCLocation instead of the actual page. Anyone else seen similar behaviour or know how we might get around this?

Anonymous

It seems that the TOC linking is not working in Confluence 4.1.3. Only the first link works, the others are broken. I think this is due to wrong syntax of the <a> anchors in the TOC. This error is very serious because to us its very importent to have a TOC above of long pages.

Has anybody had problems with TOC macro when it is on a page that it included to another page? The links work fine on the original page but looks like they do not work on the page where it is included into.

Anonymous

I have the same issue - really defeats the purpose of that parameter. I input a support ticket today because we need this to exclude from our pdfs that we generate as our user-guides. We'll see what they say...

Is there any way to automatically add an active table of contents? The "Insert -> Table of Contents" feature seems to create just a list of headers on the page, but they aren't clickable.

Also and related, is there a way to set a page so that it doesn't use the "blue and underlined" css for things that are NOT links. It is confusing when it seems to be everywhere that confluence seems to think needs emphasis.

Anonymous

I am using Stepstone's Zen editor–the TOC is messed up there. It doesn't update with the latest additions. I know you guys don't support Stepstone plugin, but the TOC macro is Atlassian's. They don't seem to work well inside Zen's editor.

Anonymous

I'm trying to add a TOC to my wiki article, however my article has other articles embedded in it(cloaked). I only want the TOC to display headings from my article. Is there a proper solution to this? Thanks in advance.

Guys, This product is amazing, but I am having issues with exporting to PDF, I have been working for a few days at the export to pdf functionality. I have successfully configured the multi-page export to PDF to work properly. All pages are exported to a single document with a page-by-page index as the title page, unfortunately all of the TOC that I have on multiple pages do the same thing and force a page-break before and after the TOC, this makes the PDF export longer than necessary and inconsistent. I guarantee there is a way to fix this in the Space or Global PDF Style-sheet control but can't figure out what the content I need to add to make this work. Can anyone help with this?

I'm not aware of any workaround for this issue, however it has been fixed in Confluence 5.1.3 if you are able to upgrade. If you are an OnDemand customer you should have the fix already. You can see details on the issue here
CONF-28252
-
Page break before and after Table of Contents macro are forced in PDF exportResolved
.

Anonymous

With the latest version of Confluence On Demand, I am finding that TOC heading links to not work when the heading has a question mark in it. There is an old JIRA about this issue, but it was supposedly fixed many versions ago. Has the problem resurfaced? Is there a work around – other than not including the question mark? (It is a FAQ page, so question marks in headings are difficult to avoid!)

Hi Anonymous, I have have not been able to replicate your issue in OnDemand (for me headings with ? characters appear and work fine in the table of contents macro). You might want to raise a support issue or a bug about this.

Anonymous

Thank you for your response, Rachel. I did a bit more investigating. It appears to only be an issue on FireFox – but is definitely an issue there (including with pages in the Confluence documentation that have question marks in the headings). The links work fine on Chrome and Safari. I will log a bug.

Version 2.6.7 of the TOC plugin produces only a numbered TOC list without the heading text. Is there a bug in the plugin? or should something more be configured to also get the heading text in the TOC list?

Anonymous

I am having the same issue with my wiki's since updating to Atlassian Confluence 5.2. Pages that worked previously now display as just the numbered heading. I haven't been able to identify a bug for this yet but I suspect that we will need to search their open issues or report it in the correct forum.

Hi Ulrich, this should have been fixed - see
CONF-26765
-
Redirect to anchors in pages with titles that contain special characters is brokenResolved
. If you are using 5.2.5 or later and still experiencing this issue could you please raise a bug or contact Support?

We just upgrade confluence from 4.3.2 to 5.2.5, and Table of Content plugin has been upgraded from 2.6.1 to 2.6.10.

I found the page with TOC macro displayed differently, the table of contents in old version has Strikethrough if the contents headings contain Strikethrough, but the new version do not include Strikethrough anymore.

Hi Sherry, I've just tried this with v 2.6.10 of the Table of Contents plugin on Confluence 5.3 and it works as expected. If you continue to have problems with 5.2.5 you might want to contact Support or raise a bug.

Anonymous

I added a table of contents to my page, but now the save button is disabled. The only way I have found out of it is to close the window, and then choose to restore the previously saved version, removing the table of contents. What am I doing wrong here?

Anonymous

In the macro parameters you can specify none in the list style field to show the list with no bullet points. I'm not aware of a way to do this in the space CSS however. You might want to ask your question at Answers as someone in the community may have a solution for you.

Since the code you're referring to is in the default css already, shouldn't the Table of Contents include page numbers when printed or exported to Word/PDF as default (ie. no need to change anything to have this functionality)? We have the same problem here as Kevin, our table of contents just show the section numbers and titles, nothing else. We'd like to have dots (.) and page numbers displayed as well. Like so:

1.1 One Title ....................................................... 32

Managed to solve it myself by stumbling onto Steffen Heller's post in an Atlassian Answers thread about the TOC not being generated at all:

"The appearance of that list can be adapted and refined with CSS that you enter at Browse > Space Admin > Look and Feel > PDF Stylesheet > PDF Export Stylesheet

If you want page numbers and a dotted line you can use

1

2

3

a:after {

content: leader(dotted) target-counter(attr(href), page);

}

To avoid that all other hyperlinks on your page also get page numbers you better put your toc into another css class. For this you enter some_class_name (choose whatever you like) at "CSS Class Name" from the Edit menu of the {toc} macro and put exactly that some_class_name before the "a:after" so that you get ".some_class_name a:after" (don't forget the dot at the beginning)."

This solution created more problems that I solved while typing this, so I just thought I'd share in case anyone else gets stuck there too:

Just adding the CSS Class Name to the Table of Contents Macro Edit menu (as mentioned above), makes the TOC show disc bullets before each section number as bullet points, both in the PDF Export and on the actual page. The indentation of each section of the TOC changes, and nothing happens whatever you try to change in the Table of Contents Macro Edit menu. For example, if you leave the "List Style" input field empty, press Save, and open the Edit menu again, it will now says "disc". If you put "none" or "circle" or "square", nothing happens to the TOC. If you leave the "Heading Indent" empty, or put 15px, or 200px or anything, nothing changes. If you remove the CSS Class Name, all the Table of Contents Macro Edit menu input fields work like they should again.

So, I figured out that by entering a CSS Class Name in the Table of Contents Macro Edit menu, all TOC styling must now be done in the Global PDF Stylesheet (for the PDF Export) + the Global Stylesheet (for the actual page). So as Confluence Admin, you have to go to Global PDF Stylesheet and add your TOC styling there for your PDF export and then go to the Global Stylesheet and add your TOC styling there for your page.

For example, to have your TOC align to the left side of the page, remove any bullets (list-style-type), have an indentation of 15px for each section, a dotted line and page numbers, you'll add the following:

I'm glad you were able to get the macro working. In the macro browser, you can also click the Refresh icon to update the preview - this helps you see what your table of contents will look like without saving the page.

Is there a way you could include a page anchor (Working with Anchors) in your table of contents without adding heading styles to it? I have a long table in a page, and I use anchors in the first column of the table, and use it to link to certain parts of the table. I can manually do it, but can I use the Table of Contents Macro to do the same?

I am exporting a pdf, out from multiple confluence wiki pages. My requirement is to have a minitioc(for h1, h2, h3 etc.) at the top for each page in the exported pdf. Is this possible to generate, and how?

You can customise the layout of the PDF, and it may be possible to make a table of contents appear on each page (I'm not sure how to do it myself, but it should be possible). There's some info on this page Customising Exports to PDF and this page Advanced PDF Export Customisations. I think there is also a lot of information on Answers too.

Hi, using Confluence OnDemand, I was wondering why we have the option "Display Section Numbering" in the table of contents macro whereas we cannot have numbered headings except if we pay for the add-on, add-on that does not manage 'include' pages as numbering is reset. In such a case the "Display Section Numbering" is not necessary.

Hi Bruno, the Display Section Numbering checkbox will add a number to each item in the table of contents. It is not related to any third party add-ons that might allow actual heading numbering. For example

This is my first heading

This is my second heading

This is the table of contents with Display Section Numbering selected:

I know it is not related to the add-on but I (in fact 'we') really do not understand why we can have numbered headings in the table of contents whereas we can't have numbered headings in the document. It's like reading a book where you have a table of contents with page numbers whereas the book itself does not contain any page number. Thanks for clarification.

Yet another user here wondering why it's not possible to show numbered headings within the document. It's hard to navigate through a big page when there's duplicated heading values and not numbering available. For instance:

Feature A

Proposal

Return of Investment

...

Feature B

Proposal

Return of Investment

...

Feature C

Proposal

...

Looking at a "Proposal" heading doesn't tell me anything unless I scroll up to find what feature I'm in.