TOC Macro

Last modified by Admin on 2024/12/12 00:46

cogGenerates a Table Of Content for titles (headings)
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

Each title has an anchor associated to it.

Usage

From WYSIWYG Editor

tocMacro-wysiwygEditor.png

From Wiki Syntax

{{toc start=2 depth=6 numbered=false scope=page /}}

Parameters definition

NameOptionalAllowed valuesDefault valueAdvancedDescription
startyes1 - 61an initial level where the TOC generation should start at
XWiki 15.10.2+, 16.0.0+ It's now advised to start page content hierarchy at the H2 level, meaning that start=2 should be used.
depthyes1 - 66maximum level the TOC is generated for
numberedyestrue/falsefalseXWiki 15.4+ yesif should generate numbering for titles (see examples below)
scopeyespage/localpageIf local, only section in the current scope will be listed. For example if the macro is written in a section, only subsections of this section will be listed. Not used if a reference is specified (since in this case the scope is always page)
referenceyesReference to a pageCurrent pageThe page for which to generate the TOC for. If not specified, generate a TOC for the current page. Since 9.6RC1

Heading numbering in TOC

While this macro propose a minimal numbering with the numbered parameter, the Numbered Headings Application offers a TOC macro that overrides the default one and adds more numbering features.

Styling

XWiki 14.10+ The root list element of the TOC macro has the class wikitoc which can be targeted with CSS to style the TOC macro, e.g., in a skin extension.

XWiki 15.2+ The items of the TOC that are empty because they are skipped (e.g., when a H3 level heading directly follows a H1) are annotated with the nodirectchild class.
The class can be using in CSS selector to style the TOC macro, e.g., in a skin extension.

Examples

Example 1: Simple

{{toc /}}

= Level 1

Hello

== Level 2

Result

toc1.png

Example 2: Floating

{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}

= Level 1

Hello

== Level 2

Result

toc2.png

Example 3: Different numbering of sub lists

With a bit of CSS you can change the numbering of subitems. For example add a StyleSheetExtension Object to your page and put the following content (select Always on this page):

ol { list-style-type: none; counter-reset: say; }
ol li:before { counter-increment: say; content: counters(say,".") ". "; }

With this extension, the following content will have, for example, Level 2 displayed as 1.1 (see Result below):

{{toc numbered="true"/}}

= Level 1
== Level 2
== Level 3
= Level 4
== Level 5

Result

toc3.png

Developers

XWiki 15.8+

Customize the entries

It is possible to extend the content of the ToC entries by providing a component with the TocEntryExtension role.
Each TocEntryExtension are executed in turn, each taking the return of the previous one.

/**
 * Table of content entry extension, allowing to intercept and improve the default rendering of the table of content
 * entries.
 * <p>
 * For instance, this component can be used by the numbered content application to prefix each entry with an
 * auto-generated number, matching the number used as a prefix for the corresponding header.
 *
 * @since 15.8RC1
 */

@Role
@Unstable
public interface TocEntryExtension
{
   /**
     * Allow to decorate a table of content entry.
     * <p>
     * For instance, the numbered content extension can decorate the table of content entries by prefixing each entry
     * with an automatically generated number.
     * <p>
     * The {@code decorate} methods from all {@link TocEntryExtension} components are expected to be called one after
     * the other on each table of content entry. The call order is the same for all entries but is not guaranteed.
     *
     * @param headerBlock the header block to render as an entry
     * @param blocks the blocks
     * @param rootBlock the root block containing the header
     * @param tocEntriesResolver a table of content resolver, allowing to help resolving content surrounding the
     *     entry
     * @return a new list of blocks to user to display the entry
     */

    List<Block> decorate(HeaderBlock headerBlock, List<Block> blocks, Block rootBlock,
        TocEntriesResolver tocEntriesResolver);
}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.rendering:xwiki-rendering-macro-toc 16.10.1):

Get Connected