Add a Table of Contents

Articles with a lot of content often benefit from a Table of Contents, allowing visitors to understand the article’s structure at a glance and navigate to a section of the page quickly and easily.

Our Table of Contents plugin is bundled with all of our themes and allows you to instantly add your own Table of Contents element that automatically generates a set of links based on your article’s page structure. You can also easily apply a custom micro-template to customize its look-and-feel (and possible functionality) to truly make it your own.

Current versions of 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.

Below we describe how to add a Table of Contents to earlier themes or completely customize the look-and-feel of the default one to make your articles easier to consume.

Create a Table of Contents

To have a Table of Contents appear in your articles you can simply add the following snippet to the page:

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

This can be done in one of two ways:

  1. Add the snippet to the Article page template immediately above the {{article.body}} placeholder in the article_page.hbs page template:

     <section class="content" itemprop="articleBody">
       <div data-element="table-of-contents" class="table-of-contents"></div>

    This will ensure that the Table of Contents is displayed above the content on every article without your content creators having to do anything.

  2. Add the snippet within your article content using the Source Code view in the Zendesk Guide article editor. This approach allows your content creators to control which articles the Table of Contents appears on and which it does not.

You can control how the Table of Contents works by passing option values as data attributes. For example, to only show <h2> and <h3> headings within the article content area, you could use:

<div data-element="table-of-contents" data-selector=".content > h2, .content > h3"></div>

By default, the Table of Contents will render a simple unordered list:

Styling the Table of Contents

If you’d like to give your Table of Contents its own unique look-and-feel there are a couple of options.

Custom CSS

One option is to write some custom CSS.

For example, if you add a class name of .table-of-contents to your Table of Contents element:

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

You can then customize the appearance of elements rendered by the plugin. For example, you could change the link color to red:

.table-of-contents a {
  color: red;

Custom micro-template

Another option is to create a custom micro-template. You can radically change the layout and style of the Table of Contents and even add new functionality.

For example, if you wanted to use the following custom Table of Contents micro-template:

<script type="text/html" id="tmpl-table-of-contents">
  <% if (items.length > 2) { %>
      In this article
    <ol class="font-size-md list-inside p-0 mb-6">
      <% items.forEach(function(item) { %>
        <li class="text-gray-700 border-bottom">
          <a class="inline-block py-3 px-2 text-inherit hover:no-underline" href="<%= item.html_url %>">
            <%= %>
      <% }); %>
  <% } %>

You’d add the template to the Article page or the Footer template (which is globally available) and specify the template ID using the template option as a data-attribute.

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

The number of items depends on how you’ve configured your Table of Contents.

This template will only display the title and list items if there are two or more items to display. Although not necessary, you can include other conditions in your template to further control when and how it appears.

The end result is a Table of Contents with a title and updated look-and-feel:

If you support multiple languages in your Help Center you can use dynamic content to ensure that labels used in your templates are automatically translated. Simple replace static “In this article” heading text in your micro-template with dynamic content using Zendesk’s dynamic content helper.

Plugins can also work together to provide unique customer experiences. An example can be found in our Kai theme in which a Table of Contents is made sticky and tracks the visitors position on the page using our Scrollspy plugin.

Questions or feedback about this guide? Let us know