This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

Table-of-Contents Macros

 27th April 2023 at 12:55pm

TiddlyWiki provides several macros for generating a tree of tiddler links by analysing tags:

toc
A simple tree
toc-expandable
A tree in which all the branches can be expanded and collapsed
toc-selective-expandable
A tree in which the non-empty branches can be expanded and collapsed
toc-tabbed-internal-nav and toc-tabbed-external-nav
A two-panel browser:
  • on the left, a selectively expandable tree that behaves like a set of vertical tabs
  • on the right, the content of whichever tiddler the user selects in the tree

The difference between the last two has to do with what happens when the user clicks a link in the right-hand panel:

toc-tabbed-internal-nav
The target tiddler appears in the right-hand panel, replacing the tiddler that contained the link
toc-tabbed-external-nav
The target tiddler appears in the normal way (which depends on the user's configured storyview)

Structure

The top level of the tree consists of the tiddlers that carry a particular tag, known as the root tag. Tiddlers tagged with any of those make up the next level down, and so on.

At each level, the tiddlers can be ordered by means of the list field of the parent tag tiddler. They can also be ordered by the macro's sort parameter.

The tree displays the caption field of a tiddler if it has one, or the tiddler's title otherwise.

Each tiddler in the tree is normally displayed as a link. To suppress this, give the tiddler a toc-link field with the the value no. In the examples, the SecondThree tiddler is set up like this. Clicking such a tiddler in the tree causes its branch to expand or collapse.

Introduced in v5.1.23 By default, the links open the tiddlers making up the table of contents. Alternatively, if the tiddler contains a target field then its contents will be used as the target of the link.

The table of contents is generated as an HTML ordered list. The <ol> elements always have the class tc-toc. Expandable trees have the additional class tc-toc-expandable. Selectively expandable trees (including those in the two-panel browser) have tc-toc-selective-expandable.

To make a table of contents appear in the sidebar, see How to add a new tab to the sidebar.

Parameters

tag
The root tag that identifies the top level of the tree
sort
An optional extra filter step, e.g. sort[title]

These two parameters are combined into a single filter expression like this:

[tag[$tag$]$sort$]

toc-tabbed-internal-nav and toc-tabbed-external-nav take additional parameters:

selectedTiddler
The title of the state tiddler for noting the currently selected tiddler, defaulting to $:/temp/toc/selectedTiddler. It is recommended that this be a system tiddler
unselectedText
The text to display when no tiddler is selected in the tree
missingText
The text to display if the selected tiddler doesn't exist
template
Optionally, the title of a tiddler to use as a template for transcluding the selected tiddler into the right-hand panel
exclude New in v5.3.0
This optional parameter can be used to exclude tiddlers from the TOC list. It allows a Title List or a subfilter. Eg: exclude:"HelloThere [[Title with spaces]]" or exclude:"[has[excludeTOC]]". Where the former will exclude two tiddlers and the later would exclude every tiddler that has a field excludeTOC independent of its value.
Be aware that eg: [prefix[H]] is a shortcut for [all[tiddlers]prefix[H]], which can have a performance impact, if used carelessly. So use $:/AdvancedSearch -> Filters tab to test the exclude parameter

Custom Icons

Introduced in v5.2.4

To change the icons used by the Table-of-Contents macros, redefine the macros toc-open-icon and toc-closed-icon. This setting works for all toc-macro variants.

Default Settings

  • toc-open-icon: \define toc-open-icon() $:/core/images/down-arrow
  • toc-closed-icon: \define toc-closed-icon() $:/core/images/right-arrow

Custom Definitions

The default settings can be overwritten in your code using the define-pragma or the let-widget. The $let widget can be used, if you have multiple table of contents macros in one tiddler, that need different icons.

Define new icons using a pragma

\define toc-open-icon() $:/core/images/fold-button
\define toc-closed-icon() $:/core/images/folder
...

Define new icons using the let-widget

<$let toc-open-icon="$:/core/images/fold-button" toc-closed-icon="$:/core/images/folder">
...
</$let>

Examples

Learn more at Examples