Table of Contents Macro
Add the Table of Contents macro to a page to help your readers skip directly to the information they’re looking for.
This macro is great for situations where:
you have a large page with lots of information
you want to build your headings into a neat table of contents.
This macro is popular because it helps you navigate lengthy pages. The macro organises your table of contents by nesting Heading 2 under Heading 1, and indenting progressively, like in the image below.
On this page:
Screenshot: Table of Contents macro neatly organises lengthy blog content.
Using the Table of Contents macro
To add the Table of Contents macro to a page:
- From the editor toolbar, choose Insert
> Other Macros. - Choose Table of Contents from the Confluence content category.
- Enter any parameters.
- Choose Insert.
You can then publish your page to see the macro in action.
Screenshot: Entering parameters for the Table of Contents macro.
Change the macro parameters
Macro parameters are used to change the behaviour of a macro.
To change the macro parameters:
- In the editor, click the macro placeholder and choose Edit.
- Update the parameters as required then choose Insert.
Here's a list of the parameters available in this macro.
Parameter | Default | Description |
|---|---|---|
Output Type | list |
|
Display Section Numbering | clear | Select the check box to apply outline numbering to your headings, for example: 1.1, 1.2, 1.3. |
List Style | disc | Select the style of bullet point for each list item. You can use any valid CSS style. For example:
|
Heading Indent | Sets the indent for a list according to CSS quantities. Entering | |
Separator | brackets | This parameter applies to flat lists only. You can enter any of the following values:
|
Minimum Heading Level | 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 | 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 | 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 | 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 | 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 | If you have custom TOC styles in your CSS style sheet, use this parameter to output the TOC inside | |
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. |
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).
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 'Favorite', 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:
Other ways to add this macro
Add this macro as you type
Add this macro using wiki markup
This is useful when you want 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.
{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.
{toc:printable=true|maxLevel=2|minLevel=2|class=bigpink|exclude=[1//2]|type=flat|outline=true|separator=pipe|include=.*}Notes and known issues
- 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.
- 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 macro
The 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.
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.<h2><a name="pagename-headingname"></a>Heading Name</h2>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.
- There is a known issue where if you click a heading in the Table of Contents macro, then click the back button in your browser, you won't be returned to the table of contents (or to your previous page). As a workaround, use the Table of Content Zone Macro. See CONFSERVER-40462 - Getting issue details... STATUS and CONFSERVER-52497 - Getting issue details... STATUS for more information.
Do more with Confluence
Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace. Here's some specific to documentation:
- Scroll Office for Confluence - turn your Confluence pages pages into professionally styled documents
- Advanced Children Display for Confluence: combine Confluence's built-in children display and table of contents macros