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.
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.
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.
- Customize your theme within Zendesk Guide.
- Click on the Article page elements section.
- 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.
- 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">
document.addEventListener('DOMContentLoaded', () => {
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 | stringDOM elementnull | 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 | stringnull | 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. |
