Table of Contents Macro

Using the Table of Contents macro

Hint: For quick access from the editor toolbar, choose Insert > Table of Contents.

To add the Table of Contents macro to a page:

1. From the editor toolbar, choose Insert > Other Macros
2. Find and select the required macro

Speed it up with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. In this example we're inserting the cheese macro.

To edit an existing macro: Click the macro placeholder and choose Edit. This will open the macro details, so you can edit the macro parameters.

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

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.

Favourite.*

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

2

Unknown.*

The resulting table of contents is:

Wiki markup example

This example 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 Gathering Impact  and  CONFSERVER-52497 Gathering Impact  for more information.