about.page

---
title: Table of Contents
description: Generates table of contents automatically.
icon: 'M3,9H17V7H3V9M3,13H17V11H3V13M3,17H17V15H3V17M19,17H21V15H19V17M19,7V9H21V7H19M19,13H21V11H19V13Z'
color: '#f954ad'
image: /lot/x/t-o-c/index.png
author: Taufik Nurrohman
type: Markdown
version: 3.0.1
...

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](https://github.com/mecha-cms/x.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:

~~~ .md
### Heading Level 3 {#asdf}
~~~

~~~ .html
<h3 id="asdf">Heading Level 3</h3>
~~~

~~~ .html
<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:

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

~~~ .html
<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`:

~~~ .yaml
---
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:

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

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

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

 *[TOC]: Table of Contents