wiki:TocMacro

Display Table of Contents

Description

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

[[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 page name 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 Suppress display of page title.
reverse Display TOC sorted in reverse order, since 0.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)]]

As an example of the usage of this macro:

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

Alternative: Trac 0.12 has the 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)]]

Bugs/Feature Requests

Existing bugs and feature requests are here.

If you have any issues, create a new ticket.

defect

44 / 61

enhancement

15 / 35

task

0 / 1

Download

Download the zipped source from here.

Source

You can check out TocMacro from here using Subversion, or browse the source with Trac.

Installation

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

$ easy_install https://trac-hacks.org/svn/tocmacro/0.10   # 0.10
$ easy_install https://trac-hacks.org/svn/tocmacro/0.11   # 0.11, 0.12, 1.0

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

Enable the plugin in your trac.ini file:

[components]
tractoc.* = enabled

Recent changes

15937 by rjollos on 2016-10-27 22:44:36
11.0.0.6: Skip permission check on resource containing the TOC

Permission must have already been granted on this resource
if the macro is being executed. An effect of this change is that
TOC can be used in resources other than wiki pages, such as
blog posts, as long as the TOC is only created for the post
containing the TOC macro.

Fixes #12914.

15935 by rjollos on 2016-10-26 21:25:12
11.0.0.5: Cleanup whitespace
14544 by rjollos on 2015-04-20 16:03:19
11.0.0.5: tag_svn_revision is not supported in setuptools ≥ 10.
(more)

Author/Contributors

Authors: athomas, jouvin, coderanger, cboos, osimons
Maintainer: none (needsadoption)
Contributors:

Last modified 6 weeks ago Last modified on Oct 26, 2016, 9:35:17 PM