Table of Contents

Generate a table of contents for your articles automatically, allowing your visitors to view the page structure at a glance.

A configurable table of contents is included with all of our themes. By default it displays links for every <h2> heading in your article content within a stylish element at the top of the page or in a sidebar. There’s no need to copy and paste any HTML or make changes to your article content or page templates.

Boxed style table of contents

Our themes allows you to select from one of several built-in table of contents styles using the Table of Contents theme setting in the Article page elements setting group.

Sticky table of contents

Combining a table of contents with our Scrollspy extension allows you to create floating elements that track the visitor’s position on the page as they scroll. For more examples, take a look at our Table of Contents patterns.

The table of contents will inherit the overall style of the theme as defined in your theme settings. The heading above the links is also configurable within theme settings. You can customize the Table of Contents further, both in terms of its appearance and functionality, through extension options and custom micro-templates.

Creating a table of contents

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.

The Table of Contents extension is bundled into all of our themes by default, so you can start using it straight away. You can find the source code for the extension within the extensions.(min.)js file in the theme’s Assets folder.

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. Select a style from the Table of Contents setting to display a table of contents on the Article page either above the content or in a sidebar.
  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" data-selector=".content h2"></div>

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

You can create a new instance of the Table of Contents extension 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 extension are contained.
selector string '.content h2' The CSS selector used to identify sections.
anchorLinks boolean true True if the extension should generate anchor links for headings.
generateIds boolean true True if the extension 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 micro-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.

Related extensions

Animations and transitions Free

Animations and transitions

Add engaging animation and transition effects to elements.

Carousels Free

Carousels

Present content in well-defined and easy to follow steps.

Content blocks and icons Free

Content blocks and icons

Display icons against categories, sections and articles.