Confluence Table of Contents
Long pages overwhelm readers. A table of contents solves the problem by listing every heading at the top of the page, with each entry linking straight to its section. Confluence builds the list automatically through a macro, so the list updates whenever headings change.
Why Headings Matter
The macro reads the heading styles on your page. Text formatted as Heading 1 through Heading 6 becomes an entry. Bold text that only looks like a heading stays invisible to the macro. Use real heading styles for every section title.
Adding the Macro
- Open the page in the editor.
- Type a slash and the words table of contents.
- Press Enter to insert the macro near the top of the page.
- Publish the page and click any entry to test the jump.
How the Output Looks
PAGE: Onboarding Handbook
[ Table of Contents ]
1. Welcome
2. First Week
2.1 Laptop Setup
2.2 Account Access
3. Benefits
4. Support Contacts
--------------------------------
Welcome (Heading 1)
First Week (Heading 1)
Laptop Setup (Heading 2)
Account Access (Heading 2)
Heading levels decide indentation. A Heading 2 under a Heading 1 appears as a sub-entry.
Macro Options
Click the macro and choose edit to open its settings. Options vary by edition, and the most common ones follow.
| Option | What It Does | Example Use |
|---|---|---|
| Minimum heading level | Sets the highest heading shown | Start at Heading 2 to skip page titles |
| Maximum heading level | Sets the deepest heading shown | Stop at Heading 3 to keep the list short |
| List style | Chooses bullets, numbers, or none | Use numbers for manuals |
| Layout | Switches between a vertical list and a horizontal row | Use a row for a compact menu |
| Exclude headings | Hides entries that match a pattern | Hide the "Revision History" heading |
Related Navigation Macros
Children Display
The children display macro lists every child page below the current page. A parent page named "Policies" can show links to all policy pages without manual updates.
Include Page
The include page macro pulls the full content of another page into the current one. Update the source and every page that includes it updates too.
Excerpt and Excerpt Include
The excerpt macro marks a short passage on a page. The excerpt include macro shows only that passage on another page. A project summary written once can appear on ten dashboards.
Source page Other pages +--------------+ +-----------------+ | [Excerpt] | ----> | Excerpt Include | | Project goal | | shows the goal | | [/Excerpt] | +-----------------+ +--------------+
Design Tips for Readable Pages
- Keep section titles short and descriptive.
- Limit the list to two heading levels on pages under ten sections.
- Place the macro below a short introduction so readers get context first.
- Avoid skipping heading levels, such as jumping from Heading 1 to Heading 4.
Troubleshooting
An empty table of contents means the page has no heading styles. A missing section means the heading uses plain bold text. Excluded headings vanish when a pattern matches too broadly, so test the filter after every change.
A Worked Example
Imagine a 3,000-word troubleshooting guide with eight main sections and several sub-sections. Without navigation, a reader scrolls for a full minute to reach the last section. With the macro, one click lands on the target heading. The macro also helps writers, since the outline reveals gaps and uneven section sizes at a glance.
| Before the Macro | After the Macro |
|---|---|
| Readers scroll and guess | Readers click and arrive |
| Structure stays hidden | Structure shows at the top |
| Long pages feel heavy | Long pages feel organised |
Printing and Exporting
Exported PDFs keep the table of contents, and the entries usually link to the matching sections. Check the export once, since layout details change with the format.
Key Takeaways
- The macro builds a clickable outline from your headings.
- Real heading styles power the list.
- Level limits and exclusions keep the outline tidy.
- Children display, include page, and excerpt macros extend navigation.