• Products
  • Documentation
  • Resources
Products
Documentation
Resources
Atlassian Support
/
Confluence
/
Resources
/
Extend the functionality of Confluence Cloud
/
Use macros to add navigation on Confluence pages
Cloud

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 the Table of Contents macro: 

table of contents macro

  1. When editing, select from the toolbar

  2. Find the macro by name and select it

  3. Configure it as needed

You can also type / on the page to bring up the same list you'd see by selecting from the toolbar. Continue typing the name of the macro to filter the list.

To edit the Table of Contents macro: 

  1. Select the macro placeholder.

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

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan iconto remove the macro.

Parameters

Parameters are options that you can set to control what and how content from the macro appears on the page. 

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).

Parameter

Default

Description

Output Type
(type)

list

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

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

Display Section Numbering
(outline) 

clear

Select the check box to apply outline numbering to your headings, for example: 1.1, 1.2, 1.3.

List Style
(style) 

disc

Select the style of bullet point for each list item.  You can use any valid CSS style.  For example:

  • none — no list style is displayed

  • circle —  the list style is a circle

  • disc — the list style is a filled circle. This is the typical bullet list, and is used for this example list.

  • square — the list style is a square

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

  • lower-alpha — the list is lower-case, alphabetized (a, b, c, d, e)

  • lower-roman — the list style is lower roman numerals (i, ii, iii, iv, v, vi)

  • upper-roman — the list style is upper roman numerals (I, II, III, IV, V, VI)

Heading Indent
(indent) 

 

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.

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
(exclude) 

 

Filter headings to exclude according to 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.

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. 

 

Examples

The examples below are based on this table of contents structure:

See an example of a table of contents without filters

Filtered Table of Contents

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

Parameter

Value

List Style

upper-roman

Include Headings

1 Favourite.*

Exclude Headings

1 .*Things

The resulting table of contents would be:

See what a shows up when you filter a table of contents

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

1 2

Include Headings

1 Unknown.*

The resulting table of contents would be:

See what shows up when you display a table of contents as a flat list

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, 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.)

  • The Table of Contents macro only displays page or blog post content. You can't use it to add a table of contents of headings in a comment for example. 

  • 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

On this pageUse the Table of Contents macroParametersExamplesFiltered Table of ContentsWiki markup exampleNotes
CommunityQuestions, discussions, and articles