The {toc} macro displays a table of contents based on headings present on the page...
If you have a lot of information on a page, it's a good idea to break it in to sections by using Headings in order to make it more readable. You can then use this macro to display a contents list based on those headings.
The {toc} macro has the following parameters:
{toc:parameters}
Parameters
Parameter
Required
Default
Notes
type
list
The type of output, either:
list (default) - a hierarchical list of links to headings
flat - a flattened (single line) list
class
An optional CSS class to associate the table with. If specified, no other formatting information will be used (style, indent, etc) allowing you full control over the display.
style
The style of bullet point to use for each item when using the list type:
none - no marker
Any valid
Unknown macro: {glossary}
CSS
style (see the Styles tab above)
indent
10px
When using the list type, this parameter set the indentation to use for each nested level of the contents. Any valid CSS size value can be used, but remember to specify the units (e.g. "px" for pixels).
separator
brackets
When using the flat type, this parameter defines how individual items will be separated from one another:
brackets (default) - items will be enclosed in [USERGUIDE:square] [USERGUIDE:brackets]
brace - items will be enclosed in {curly} {braces}
parens - items will be enclosed in (normal) (brackets)
pipe - items will be separated | by | pipes
Anything else - a custom separator
minLevel
1
The minimum heading level to include in contents list - a number between 1 and 6 corresponding to the heading level. Must be less than or equal to the "maxLevel" parameter.
maxLevel
6
The maximum heading level to include in contents list - a number between 1 and 6 corresponding to the heading level. Must be greater than or equal to the "minLevel" parameter.
includePages
false
If set to true, then the contents will also include any headings within included pages within the current page (see [USERGUIDE:include macro]).
filter
Allows you to use a Regular Expression to filter headings based on matching criteria. Not for the feint hearted!
printable
true
If set to false the table of contents will not be displayed in a print preview.
outline
false
If set to true, items will be uniquely numbered in a 1.2.3 style.
The following chart shows examples of the
Unknown macro: {glossary}
CSS
styles that can be used and how they look in your own web browser:
disc:
Item 1
Item 2
Item 3
Item 4
circle:
Item 1
Item 2
Item 3
Item 4
square:
Item 1
Item 2
Item 3
Item 4
decimal:
Item 1
Item 2
Item 3
Item 4
decimal-leading-zero:
Item 1
Item 2
Item 3
Item 4
lower-roman:
Item 1
Item 2
Item 3
Item 4
upper-roman:
Item 1
Item 2
Item 3
Item 4
lower-alpha:
Item 1
Item 2
Item 3
Item 4
upper-alpha:
Item 1
Item 2
Item 3
Item 4
lower-greek:
Item 1
Item 2
Item 3
Item 4
lower-latin:
Item 1
Item 2
Item 3
Item 4
upper-latin:
Item 1
Item 2
Item 3
Item 4
hebrew:
Item 1
Item 2
Item 3
Item 4
armenian:
Item 1
Item 2
Item 3
Item 4
georgian:
Item 1
Item 2
Item 3
Item 4
cjk-ideographic:
Item 1
Item 2
Item 3
Item 4
hiragana:
Item 1
Item 2
Item 3
Item 4
katakana:
Item 1
Item 2
Item 3
Item 4
hiragana-iroha:
Item 1
Item 2
Item 3
Item 4
katakana-iroha:
Item 1
Item 2
Item 3
Item 4
The first two columns above are the most widely supported styles. The other styles generally require an operating system and web browser both capable of rendering
Unknown macro: {glossary}
Unicode
characters.
The following chart shows what the styles should look like if everything is configured properly:
The following chart shows what the styles often look like on systems that don't have full unicode support:
This plug-in is available without cost for both commercial and non-commercial purposes. However, if you have found it to be useful, particularly within a commercial environment, please consider making a donation to the author. This will encourage continued development of this and other plug-ins, as well as speeding up the response for your latest maintenance request.
If you wish to donate, it can be done easily with a credit card or bank transfer using Paymate. No account sign-up is required for credit card payments.
This macro is compatible with Confluence 1.3.x, 1.4.x and 1.5.x. It has been tested by Adaptavist with Confluence 1.4.1, 1.4.3 and 1.4.4. It has been tested by David Peterson with Confluence 1.5-DR2.
This macro is usually pre-installed with Builder accounts. If you wish to install it on your own Confluence install, please download it from the Confluence Extensions page.
Adaptavist maintain a JIRA Project for tracking bug reports and feature requests for this macro. The currently reported items are shown below:
jiraissues: Could not download[ http://jira.adaptavist.com/secure/IssueNavigator.jspa?view=rss&pid=10033&component=10049&statusIds=1&statusIds=3&statusIds=4&statusIds=5&sorter/field=updated&sorter/order=DESC&tempMax=25&reset=true&decorator=none] : caused by : Circular redirect to 'http://jira.adaptavist.com:80/secure/IssueNavigator.jspa'
By default, the list type output will use a style which displays different shapes (disc, circle, square, etc) at different levels of indentation as shown above. However, you can force all items to have the same marker using the "style" parameter:
As you can see above, the flat style defaults to putting square brackets around each item. However, there are times that you might want other styles in which case you should use the "separator" parameter:
You can use the "indent" parameter to customise the amount of indentation when using the list type. For example, you can make the output look like a normal list by setting the indentation to 0 pixels:
However, if you display this page in printable view you'll see that it's dissapeared!
Hints and Tips
Wherever applicable, you should set the "printable" parameter to false if you have set the "type" parameter to flat - flat contents lists are normally only useful as navigation shortcuts to specific headings and as such there's no point in printing them out.
Frequently Asked Questions
Q
I've got headings on the page, but some of them are not appearing in the contents?
A
Make sure you've got a space after the h1. and the actual heading: h2.This heading won't appear h2. This heading will appear
Q
How do you get those four dots as the custom separator?
A
It's just two sets of colons ":" next to each other to give ::
Q
Can I split the table of contents in to smaller chunks throughout my page?
The closest thing to that at present is the children macro but that will only list the page titles. Another alternative is the pagetree macro which again lists page titles.
It is in theory possible to mix the Metadata Plugin and the toc macro - add a toc as metadata to each page, label the page with something unique then use the various report macros to list all pages with the specific label and render out their individual toc's. Sounds hairy, but if you are desperate that's the only option I can think of at present.
Unfortunately it's not possible at present to auto-number the headings on the page. We tried creating a style sheet to do this but it only worked in the Opera browser and caused problems with other browsers which was a pity.
I'll see if we can conjure up a plugin that would number headings...
It's critical that you are using the correct version of the Utilities plugin - there have been some updates to this plugin recently and there are three versions of it - one for 1.4.x, one for 2.0.x and one for 2.1.x - if you've got the wrong versions installed, they will break because Atlassian changed the user management system in 2.1.
Adaptavist have been busy working on solutions to these problems and we hope to have several of our patches incorporated in to Confluence 2.2. This will enable plugin authors to package required libraries inside their plugin so you won't need to install Utilities plugin separately any more
The line "h1. " leads to a crash of the whole application server: (java.lang.OutOfMemoryError: Java heap space). I think the toc macro runs in an infinite loop.
I know this line makes no sence, but it happend twice a month that a user enter such a line.
I'd really like to see a "from here down"-type parameter in the toc macro. I find I often put headings before the table of contents (such as "h2. Table of Contents") which, though at the same level as subsequent headings, shouldn't be included in the ToC. It would be useful if the ToC could be configured to link/hierarchise only those headings below the ToC itself. Granted, I can use the toc-zone macro as a workaround, but feel such a parameter on would be cleaner. I tried using the first FAQ to my advantage here, but it seems to know how to work around that issue now.
I am experiencing problems when generating a TOC from a consolidation page "consolidated document", which has been created using {include} for each section.
For avoiding redundancy and ensuring consistency between page titles and headings, the heading of each page is created like this:
h1. {page-info:title}
The TOC macro in the consolidated page is used like this:
I've got the following report almost working, it reports sub-pages, and generates a TOC for each in a report column. The problem is that the link's in the TOC output don't work. The sub-pages themselves do inlclude a TOC at the top of the pages in which the links work.
Hi, once you created a table of contents by using {toc}, how to create a show/hide link to show/hide the table of contents by clicking on the link? (similar to show/hide comments.)
h2. This heading will appear
Added by
Hi,
is there a way to create a toc for a page-family or a whole space?
Cheers,
Eike
The closest thing to that at present is the children macro but that will only list the page titles. Another alternative is the pagetree macro which again lists page titles.
It is in theory possible to mix the Metadata Plugin and the toc macro - add a toc as metadata to each page, label the page with something unique then use the various report macros to list all pages with the specific label and render out their individual toc's. Sounds hairy, but if you are desperate that's the only option I can think of at present.
That sounds like fun. I guess I give it a try.
Thanx,
Eike
With outline=true the toc is numbered but the corresponging headings are not, how can this be done.
Unfortunately it's not possible at present to auto-number the headings on the page. We tried creating a style sheet to do this but it only worked in the Opera browser and caused problems with other browsers which was a pity.
I'll see if we can conjure up a plugin that would number headings...
Auto-numbering of headings would be excellent...
If I try:
Error formatting macro: toc: java.lang.NoSuchMethodError: com.atlassian.confluence.renderer.v2.macros.PageIncludeMacro.setSpacePermissionManager(Lcom/atlassian/confluence/security/SpacePermissionManager;)V
This is with Confluence 2.1.4 Build:#410
And TOC toc-plugin-1.4.7.jar
It's critical that you are using the correct version of the Utilities plugin - there have been some updates to this plugin recently and there are three versions of it - one for 1.4.x, one for 2.0.x and one for 2.1.x - if you've got the wrong versions installed, they will break because Atlassian changed the user management system in 2.1.
Adaptavist have been busy working on solutions to these problems and we hope to have several of our patches incorporated in to Confluence 2.2. This will enable plugin authors to package required libraries inside their plugin so you won't need to install Utilities plugin separately any more
Command I'm trying:
{toc:style=square|includePages=true}Utilities jar: utilities-plugin-2.1.3.jar
If you omit the "includePages" do you still get the error?
Hi,
The line "h1. " leads to a crash of the whole application server: (java.lang.OutOfMemoryError: Java heap space). I think the toc macro runs in an infinite loop.
I know this line makes no sence, but it happend twice a month that a user enter such a line.
We are using confluence 2.1.4.410.
cu,
Tobias
I'd really like to see a "from here down"-type parameter in the toc macro. I find I often put headings before the table of contents (such as "h2. Table of Contents") which, though at the same level as subsequent headings, shouldn't be included in the ToC. It would be useful if the ToC could be configured to link/hierarchise only those headings below the ToC itself. Granted, I can use the toc-zone macro as a workaround, but feel such a parameter on would be cleaner. I tried using the first FAQ to my advantage here, but it seems to know how to work around that issue now.
Updated by Volker Schneider
May 10, 2008 14:48
Hi,
I'd like to have a list of the main headlings of a page ... but cannot combine "report+toc":
1) A list of children I generate with ...only 1x {...
{{report-table}
{{local-reporter:content:children|depth=all}
{{text-sort:content:title|mode=natural|order=ascending}
{{local-reporter}
{{report-column:title=Nachfolgende Seiten|width=800px}
{{report-info:content:title|link=true}
{{report-column}
{{report-table}
2) I would like to use {{toc:maxLevel=1|style=none|outline=true|link=true}
I appreciate your help.
Updated by Greg Pendlebury
May 21, 2008 03:25
I'm just using a plain toc line with no parameters, but get this error.
Error formatting macro: toc: java.lang.NoSuchMethodError: org.w3c.tidy.Tidy.parse(Ljava/io/Reader;Ljava/io/Writer;)Lorg/w3c/tidy/Node;
We're on 2.4.4
Anybody know what could be going on?
Seems like Confluence 2.7 just got a bug with the reporting plugin. I am experience similar error as Greg when rendering
I am experiencing problems when generating a TOC from a consolidation page "consolidated document", which has been created using {include} for each section.
For avoiding redundancy and ensuring consistency between page titles and headings, the heading of each page is created like this:
h1. {page-info:title}
The TOC macro in the consolidated page is used like this:
{toc:includePages=true|style=none|maxLevel=3|indent=15px|printable=false}
The resulting TOC is:
1 consolidated document
1.2 consolidated document
1.3 consolidated document
2 consolidated document
2.2 consolidated document
3.3 consolidated document
...
Which is not the desired result.
Is there a possibility to tell the TOC macro to use the headings as they are actually rendered?
Any help would be greatly appreciated !!
David
I've got the following report almost working, it reports sub-pages, and generates a TOC for each in a report column. The problem is that the link's in the TOC output don't work. The sub-pages themselves do inlclude a TOC at the top of the pages in which the links work.
The report generated TOC link seems to omit the actual target page...
Here is the example report I used:
{report-table} {content-reporter:type=page|scope=@self>children} {text-sort:content:title|order=ascending} {content-reporter} {report-column:title=Category|width=150px}{report-info:content:title|link=true} {color:#909090}{report-info:content:excerpt}{color}{report-column} {report-column:title=Topics|width=400px}{toc:outline=true|link=true|indent=0px}{report-column} {report-column:title=Last Modifier}{report-info:content:modifier|link=true}{report-column} {report-column:title=Updated}{report-info:content:modification date|format=dd MMM @ h:mm a}{report-column} {report-column:title=Comments}{report-info:content:all comments > collection:size}{report-column} {report-column:title=Page Labels}{report-info:content:labels|link=true}{report-column} {report-table}Any pointers on how to fix?
Hi, once you created a table of contents by using {toc}, how to create a show/hide link to show/hide the table of contents by clicking on the link? (similar to show/hide comments.)