Sections

Table of Contents

Allow visitors to view the structure of a page and easily navigate its content.

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.

Example

Our themes allow you to enable Table of Contents elements on Article pages using theme settings. Once enabled, a Table of Contents will be displayed for all articles that have two or more <h2> headings.

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

You can enable and disable a Table of Contents on the Article page with a single click using theme settings.

  1. Customize your theme within Zendesk Guide.
  2. Click on the Article page elements section.
  3. Enable the Table of Contents setting to display a Table of Contents on all the Article page.
  4. Use the Table of Contents heading setting to control the heading displayed above the links.

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

Use data-element="table-of-contents" on any HTML element to transform it into a Table of Contents on page load. Typically you would add this on the Article page template (article_page.hbs).

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

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- and use kebab case instead of camel case.

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.