This extension automatically displays a table of contents on top of the page content. It detects the presence of heading elements in the page content to form the table of contents. If you just need the jump link feature without a table of contents, you might be more interested in the Anchor extension.

Usage

You have complete control to specify your own heading ID using Markdown Extra syntax or plain HTML markup. This extension will not overwrite the specific ID you specify in the heading elements:

### Heading Level 3 {#asdf}

<h3 id="asdf">Heading Level 3</h3>

<p aria-level="3" role="heading">Heading Level 3</p>

Add a role attribute with a value other than heading to the desired heading elements to exclude them from the table of contents tree. This will also disable the automatic creation of permanent link IDs:

### (Not) Heading Level 3 {role='text'}

<h3 role="text">(Not) Heading Level 3</h3>

Visibility

You can hide the table of contents on a particular page by adding this property to the state property of the page with a value that can be evaluated as a boolean false:

---
title: Page Title
description: Page description.
state:
  x:
    t-o-c: false
...

Page content.

Placement

To place the table of contents elements in a different location (for example, in the sidebar of the layout), you first need to remove the built-in table of contents hook so that this extension won’t automatically insert the table of contents elements:

Hook::let('page.content', "x\\t_o_c\\page__content\\tree");

Then you can display the table of contents elements as follows:

<aside>
  <?php if ($site->is('page') && $content = $page->content): ?>
    <h4>
      <?= i('Table of Contents'); ?>
    </h4>
    <?= To::TOC($content); ?>
  <?php endif; ?>
</aside>