Sections

Table of Contents

Allow visitors to view the structure of a page and easily navigate between sections.

In this article

Commonly used on the Article page, the Table of Contents plugin provides an overview of the structure of the page and links to each section. The plugin automatically generates the collection of links based on headings (by default <h2> tags) within the article content.

By default an unstyled list is produced however you can style and customize the Table of Contents both in terms of its look-and-feel and functionality.

An example of a Table of Contents with extra functionality provided by our Scrollspy plugin can be found in our Kai theme.

Usage

Via data attributes

You can use data attributes to create a new Table of Contents and specify values for the available options.

Use data-element="table-of-contents" attribute is used to convert an element into a Table of Contents on page load.

<div data-element="table-of-contents"></div>

Because data attributes are used, you will need to ensure that the allow unsafe HTML setting is enabled within Guide.

Via JavaScript

You can create a new instance of the Table of Contents plugin using JavaScript.

<div id="table-of-contents"></div>

<script type="text/javascript">
  ready(function() {
    var toc = document.getElementById('table-of-contents');
    if (toc) {
      new TableOfContents(toc, {
        // Options go here
      });
    }
  });
</script>

Options

Options can be passed via data attributes or JavaScript.

For data attributes, append the option name to data-.

Name Type Default Description
parentElement string
DOM element
null
null The element in which all elements considered by the plugin are contained.
selector string .content > h2 The CSS selector used to identify sections.
generateIds boolean true True if the plugin should generate IDs for headings that don’t already have one. If false, headings without an ID will not be included.
template string
null
null The name of the template to use.
templateData object {} Additional data to provide to the template rendering function.

Events

Class Properties
tableOfContents.render Fires when the table of contents markup has been rendered and inserted into the DOM.