The Table of Contents Zone macro enables you to mark out a 'page zone' from which you can use the headings to create a table of contents. Styling the headings as a flat list enables you to enclose the page text by top and bottom navigation bars similar to web navigation. When styled as a list, headings are indented progressively.

On this page:

Usage with the Macro Browser

To insert the Pagetree macro into a page using the Macro Browser,

Once you've found the Pagetree macro and have added the required parameter values, click 'insert' to add it to your page.

Usage with the Wiki Markup Editor

Include the following markup in your page:

{toc-zone:type:=[list,flat]|maxLevel=1}
Content in the zone, including other macros and page content.
{toc-zone}

There are more examples below.

Macro Parameters

Parameter

Required?

Default

Description

Location
(location)

no

both

Use this parameter to specify whether the output list displays at the top, at the bottom, or encloses the page zone content.  By default, the macro displays headings at both the top and the bottom of the page.

Output Type
(type)

no

list

Set this to "list" or "flat".  Selecting list produces a typical list type TOC.  Selecting flat produces a horizontal menu-type series of links, for example: [Heading 1] [Heading 2] [Heading 3].

Display Section Numbering
(outline)

no

false

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

List Style
(style)

no

none

Use this parameter to 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 the one we're using 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, alphabetised (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)

Separator
(separator)

no

brackets

This parameter applies to "flat" lists only.  Use this parameter to style the display of a "flat" or horizontal list.  You can enter any of the following parameters:

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

Indent

no

 

Use this parameter to style the indent for a "list" according to CSS quantities, entering "10px" will successively indent list heading groups 10px. For example, h1 headings will be indented 10px and h2 headings will be indented an additional 10px.

Minimum Heading Level
(minLevel)

no

1

Use this parameter to select the heading level to start your TOC  list.  For example, 2 will list h2, h3, and h4 headings, but will not include h1 headings.

Maximum Heading Level
(maxLevel)

no

7

Use this parameter to select the maximum heading levels to include.  For example, 2 will list h1 and h2, but will not include h3 and below.

Include Headings
(include)

no

 

Use this parameter as a way of filtering to include headings according to specific criteria. You can use wildcard characters to filter the headings. See Sun's Regex documentation for examples of constructing regular expression strings.

Because '|' is the macro parameter separator, use a comma ',' where you would normally use a '|'. If you need to match a comma, use its escape code: 'x2c'.

Exclude Headings
(exclude)

no

 

Use this parameter as a way of filtering to enclude headings according to specific criteria. You can use wildcard characters to filter the headings. See Sun's Regex documentation for examples of constructing regular expression strings.

Because '|' is the macro parameter separator, use a comma ',' where you would normally use a '|'. If you need to match a comma, use its escape code: 'x2c'.

Printable
(printable)

no

true

By default, the TOC is set to print. If you set this parameter to false, the TOC will not be visible when you print the page.

CSS Class Name
(class)

no

 

If you have a custom TOC in your CSS style sheet, you can use this parameter to output the TOC with the specified "class" attribute.

Examples

The examples are based on a page with the following headings:

h1. Places
h2. Favourite Places
h2. Unknown Places
h1. Foods
h2. Favourite Foods
h2. Unknown Foods
h1. Things
h2. Favourite Things
h2. Unknown Things

Basic Table of Contents

This will display only level 1 headings as a numbered list at the top of the page.

{toc-zone:type|location=top|type=flat|maxLevel=1}
h1. Places
h2. Favourite Places
h2. Unknown Places
h1. Foods
h2. Favourite Foods
h2. Unknown Foods
h1. Things
h2. Favourite Things
h2. Unknown Things
{toc-zone}

Filtered Table of Contents

This example will filter all headings to include those that contain "Favourite", but will exclude any heading which ends with the word "Things'. The list is styled with Roman numerals. It will not display on the printed page.

{toc-zone:minLevel=2|maxLevel=4|exclude=Adding your own Tip}
Page zone content
{toc-zone}

You can see this example 'live by visiting the Tips via Twitter page.

Flat List

This will filter all headings to render a flat list of 'Unknowns' enclosed in square brackets.

{toc:type=flat|maxLevel=2|include=Unknown.*}

Screenshot: Filtered TOC 'zone' headings displayed as flat list

Notes

RELATED TOPICS

Table of Contents Macro
Pagetree Macro
Adding a Navigation Sidebar
Working with Macros

Take me back to the Confluence User's Guide.