TableOfContentsPlugin

Yet another TOC plugin

Description

The %TOC macro, which is a part of the Foswiki core, has been updated to use a real HTML parser to extract headings. That way, a %TOC can be placed in any place you want, such as in a view template or the sidebar of a topic. The standard implementation of %TOC wouldn't allow for this.

The new %TOC is not a complete replacement due to the fundamental difference in operations. The original features, such as rendering a %TOC for a distant topic not directly part of the current page, are missing and may never be implemented.

The plugin will replace the %TOC macro with its own version by default. To use both implementations simultaneously, the $Foswiki::cfg{TableOfContentsPlugin}{ReplaceOriginalTOC} setting can be disabled. The new implementation will be accessible as the %TOC2 macro.

Syntax

Parameter	Description	Default
header	string to be prepended to the result
format	format string for each heading found, see format tokens below	$indent* <a href="$params$anchor">$text</a>
separator	string to be placed between each line of the toc	\n
footer	string to be appended to the result
depth	maximum depth of headings being displayed, a zero means unrestricted	0
title	toc title
pattern	regular expression that headings must match to be included in the output
global	boolean switch to enable "global" vs "local" rendering; in global mode will the toc render entries for the complete document; in local mode will it pick up where a previous toc left off thus rendering partial tocs	local

The format string may contain the following tokens:

• $indent: indentation based on the heading level of a toc entry
• $text: text of the toc entry
• $anchor: anchor of the heading to navigate to
• $params: url params of the page request

Any standard escapes are available as well such as $percnt, $dollar, $n etc.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
HTML::TreeBuilder	>=5	Required

Change History

30 Apr 2024	keep img tags part of a heading in the toc entry
01 Feb 2024	initial release