[[TOC]]

= Table of Contents Macro =

== Description ==

The TocMacro generates a table of contents for the current page or a set of pages.

If no arguments are given, a table of contents is generated for the current page, with the top-level title stripped:

{{{
[[TOC]]
}}}

To generate a table of contents for a set of pages, simply pass them as comma separated arguments to the TOC macro, e.g. as in

{{{
[[TOC(TracGuide, TracInstall, TracUpgrade, TracIni, TracAdmin, TracBackup,
      TracLogging, TracPermissions, TracWiki, WikiFormatting, TracBrowser,
      TracRoadmap, TracChangeset, TracTickets, TracReports, TracQuery,
      TracTimeline, TracRss, TracNotification)]]
}}}

A wildcard `*` can be used to fetch a sorted list of all pages starting with the preceding pagename stub:

{{{
[[TOC(Trac*, WikiFormatting, WikiMacros)]]
}}}

The following ''control'' arguments change the default behaviour of the TOC macro:
||= Argument     =||= Description =||
|| `heading=<x>`  || Override the default heading of "Table of Contents" ||
|| `noheading`    || Suppress display of the heading. ||
|| `depth=<n>`    || Display headings of ''subsequent'' pages to a maximum depth of '''<n>'''. ||
|| `inline`       || Display TOC inline rather than as a side-bar. ||
|| `sectionindex` || Only display the page name and title of each page in the wiki section. ||
|| `titleindex`   || Only display the page name and title of each page, similar to TitleIndex. ||
|| `notitle`      || Supress display of page title. ||
|| `reverse`      || Display TOC sorted in reversed order. //(Since 11.0.0.4)// ||

For `titleindex` argument, an empty pagelist will evaluate to all pages:

{{{
[[TOC(titleindex, notitle, heading=All pages)]]
}}}

The `sectionindex` argument allows a title index to be generated for all pages in a given section of the wiki. A section is defined by wiki page name, using `/` as a section level delimiter (like directories in a file system). Giving `/` or `*` as the page name produces the same result as `titleindex` (title of all pages). If a page name ends with a `/`, only children of this page will be processed. Otherwise, the page given in the argument is also included, if it exists. For `sectionindex` argument, an empty pagelist will evaluate to all page below the same parent as the current page:

{{{
[[TOC(sectionindex, notitle, heading=This section pages)]]
}}}

== Bugs/Feature Requests == 

Existing bugs and feature requests are [query:status!=closed&component=TocMacro&order=priority here]. If you have any issues, create a 
[/newticket?component=TocMacro new ticket].

== Installation ==

Both 0.10 and 0.11/0.12 entries at Python Package Index (pypi) are not up-to-date with latest versions and dependencies. To install the most recent versions, use direct installation from source:

{{{
#!sh
easy_install http://trac-hacks.org/svn/tocmacro/0.10   # 0.10
easy_install http://trac-hacks.org/svn/tocmacro/0.11   # 0.11, 0.12, 1.0
}}}

...or download / check out the source from repository (see below) and install it in usual manner.

Do not forget to '''enable''' the '''macro''' in trac.ini:
{{{
#!ini
[components]
tractoc.* = enabled
}}}


== Download ==

Download the zipped source from [download:tocmacro here].

TocMacro requires that AnchorPatch be applied to [wiki:0.8] Trac. Trac [wiki:0.9] already includes this patch.

== Source ==

You can check out TocMacro from [http://trac-hacks.org/svn/tocmacro here] using Subversion, or [source:tocmacro browse the source] with Trac.

== Example ==

{{{
[[TOC(inline, heading=Trac Table of Contents, TracGuide, TracInstall, depth=2,
 TracLogging, depth=99, TracPermissions)]]
}}}

On the right you can see the TOC macro version of the default !TracGuideToc macro.

== Alternatives ==

Trac 0.12 (maybe earlier?) has the [wiki:WikiMacros#PageOutline-macro PageOutline] macro built-in which can produce output identical to the simpler use cases for the TOC macro.  For example, this is equivalent to the no-argument form of TOC:
{{{
[[PageOutline(2-5, Table of Contents, floated)]]
}}}

== Change Log ==

[[ChangeLog(/tocmacro, 3)]]

== Author/Contributors ==

'''Authors:''' [wiki:athomas], [wiki:jouvin], [wiki:coderanger], [wiki:cboos], [wiki:osimons] [[BR]]
'''Maintainer:''' [wiki:osimons] [[BR]]
'''Contributors:'''