• Products
  • Documentation
  • Resources

Insert the table of contents macro

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 summarizing the content structure, and by providing links to headings. 

Any text formatted as a heading along with emojis, mentions, statuses, and dates are available for inclusion in your table of contents.

Use the Table of Contents macro

To add a Table of Contents to your page: 

  1. From the editor, select (icon) from the toolbar to bring up the insert menu.

  2. Find the Table of contents macro and select it. You can also type /tableofcontents to select this macro from the insert menu right in the body of your page.

table of contents macro

3. Upon selection, the Table of Contents placeholder will appear in the body of your page.

Image of the iframe placeholder for Table of Contents macro

4. Your table of contents won’t be visible while editing. When you preview the page or publish it, you’ll be able to see an auto-generated table of contents based on the page’s headings.

 

To configure your Table of Contents: 

  1. From the editor, select the Table of Contents placeholder.

  2. Select the Edit () icon to open the configuration panel.

  3. Customize the parameters of your table of contents in either Basic or Advanced mode.

  4. Your selections won’t be visible while editing. When you preview the page or publish it, you’ll be able to see how your customized table of contents looks.

  5. As you continue editing the page, the configuration panel will close.

You can also select the centered, medium-width, or full-width icon to adjust the width of your table of contents. Select the copy icon to duplicate it elsewhere, and/or the trashcan icon to remove it entirely.

Parameters

Parameters are options that you can configure to control exactly how your table of contents appears on the page. 

To customize your table of contents, you can configure its basic and/or advanced parameters, depending on your needs and preference.

Basic parameters

Basic parameter

Default

Description

Example

Display as

Vertical list

  • Vertical list — produces a typical list-type table of contents.

  • Horizontal list — produces a flat, horizontal menu-type series of links.

Image of a horizontal table of contents list
Image of vertical table of contents list

Bullet style

Bullet

This parameter applies to vertical lists only.

Select from any of the following values:

  • None — no bullets are displayed

  • Mixed —  the bullet style is a mix of shapes, filled and open

  • Bullet — the bullet style is a filled circle.

  • Circle —  the bullet style is an open circle

  • Square — the bullet style is a filled square

  • Numbered — the list is numbered (1, 2, 3, 4, 5)

Image of "none" option for bullet style in table of contents
Image of "mixed" bullet style for table of contents
Image of "Bullet" style of bullet for table of contents
Image of "Circle" bullet style for table of contents
Image of "Square" bullet style for table of contents
Image of "Numbered" style for table of contents

Separate sections by

Bracket

This parameter applies to horizontal lists only.

Select from any of the following values:

  • Bracket — Each item is enclosed by square brackets: [ ]

  • Brace — Each item is enclosed by braces: { }

  • Pipe — Each item is separated by a pipe: |

Image of "Bracket" separator style for table of contents
Image of "Braces" separator style for table of contents
Image of "Pipe" separator style for table of contents list

Include heading levels from [#] to [#]

1-6

Select the minimum and maximum heading levels to include in your table of contents.

Image of default heading levels included in Table of contents

Include section numbers

Unchecked

Select the checkbox to apply outline numbering to your headings. (Example: 1.1, 1.2, 1.3)

Image of Numbered Sections checkbox checked for table of contents

Advanced parameters

For advanced parameters, if the parameter name used in Confluence Cloud storage format or wikimarkup is different than the label used when inserting macros using the browser or the slash command, it will be listed below in brackets (example).

Advanced parameter

Description

Indent headings
(indent

Sets the indent for a vertical list according to a valid CSS unit value.

Entering 10px will successively indent heading groups by 10px. Level 1 headings will be indented 10px and level 2 headings will be indented an additional 10px.

Include Headings with:
(include

Filter headings to include in your table of contents by inputting specific criteria. You can use wildcard characters.

If you only want the Overview and Summary headings to appear, enter Overview|Summary in this field.

 

This field is case-sensitive.  Enter both forms of the word if you want both instances to be included.

Exclude Headings with:
(exclude

Filter headings to exclude from your table of contents by inputting specific criteria. You can use wildcard characters.

If the headings you want to exclude are Overview and Summary, enter Overview|Summary in this field.

 

This field is case-sensitive.  Enter both forms of the word if you want both instances to be excluded.

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.

Exclude in PDF export
(printable

If the box is checked, the TOC will not be visible when you export the page to PDF and/or print it.

Wiki markup example

Wiki markup is only supported in the legacy editor.

Wiki markup is useful when you need to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: toc

Macro body: None.

This example shows a list-type table of contents.

1 2 3 4 {toc:printable=true|style=square|maxLevel=2|indent=5px|minLevel=2|class=bigpink|exclude=[1//2]|type=list|outline=true|include=.*}

This example shows a flat table of contents.

1 2 3 4 {toc:printable=true|maxLevel=2|minLevel=2|class=bigpink|exclude=[1//2]|type=flat|outline=true|separator=pipe|include=.*}

Notes

  • When you use a Table of Contents macro in a template, the TOC won’t render in the template itself. But the Table of Contents macro will always work on pages created from the template – after the page has been saved.

  • The Table of Contents macro only displays page or blog post content.

  • The Table of Contents macro only works within the page, blog, or macro to which it has been added, and cannot reference or be referenced across multiple pages or blogs. When added to an Excerpt macro, for example, it will only display headings located inside the excerpt and those heading links won’t navigate to the source page.

 

Additional Help