12 Days of Confluence Elements: Day 12 - Table of Contents macro

If you’ve made it this far - thank you! Let me know other themes you’d like to cover in the next season.

The Table of Contents macro scans the headings on the current Confluence page to create a table of contents based on those headings.

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

When would you use Table of Contents macro?

This helps readers find their way around lengthy pages, by summarizing the content structure, and by providing links to headings. A rule of thumb is to use the Table of Contents macro when your article requires scrolling past the “fold” of a page. Users generally familiar with the page may be looking for a specific section, and the Table of Contents macro can help them navigate to the specific content they’re looking for.

Where is this used in our instance?

An example of the Table of Contents macro is found on Viewing and maintaining a student's academic standing (SHAINST/SGASTDN). Rather than using a formatted heading for “On this page”, we use bolded Normal text to prevent the heading from pulling into the macro.

 

Use the Table of Contents macro

To add a Table of Contents to your page: 

  1. From the editor, select Insert 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.

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

  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

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

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)

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: |

Include heading levels from [#] to [#]

1-6

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

Include section numbers

Unchecked

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

Advanced parameters

Advanced parameter

Description

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.

 

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.