Last updated

Page table of contents

Important

Page table of contents is supported on MDX pages starting with version 1.1.0-beta.47 of the Portal.

The same Portal version introduced changes to table of contents configuration options. This guide has been updated to distinguish between the Old and New configuration approach.

Add a table of contents (TOC) automatically to any Markdown or MDX page.

You can see an example of what it looks like on the right side of this page.

This guide describes:

  1. How to enable or disable the TOC globally
  2. How to override TOC settings for any specific page(s)
  3. How content is sourced for the TOC

Configure the TOC globally

To enable the TOC on all pages, add this to the siteConfig.yaml file:

  1. New
  2. Old
toc:
  enable: true

The TOC is disabled by default. If you want to disable it explicitly, add this to the siteConfig.yaml:

  1. New
  2. Old
toc:
  enable: false

Control the TOC maximum depth

You can control the maximum depth of the TOC. The maximum depth refers to how many heading levels render in the TOC (h1, h2, h3, h4, h5, h6...).

Set it using a numeric value corresponding to the heading level.

The default value in the portal is 4, meaning the portal displays h1, h2, h3, and h4 headings in the TOC (except for the initial h1, which is interpreted as the page title).

You can adjust the maximum depth in the siteConfig.yaml file or in the front matter of any page.

  1. New
  2. Old
toc:
  enable: true
  maxDepth: 3

Override page TOC settings

You can override the global setting in the front matter of any Markdown or MDX page.

In the following example, the TOC is hidden on the page even if it is enabled globally.

  1. New
  2. Old
---
seo:
  title: Markdown example
  description: GitHub-Flavored Markdown example
toc:
  enable: false
---
Example text

Open and close the front matter appropriately using three or more dashes ---, or the front matter is invalid and display as text on your page.

Source of TOC content

The TOC content comes from the h2, h3, and h4 tags on the page.

It is also sourced from any additional h1 tags except the opening h1 tag.

A second h1 example

An h2 example

An h3 example

Any h3 content appears indented.

And an h4 example

Any h4 content appears further indented.

And an h5 too

Any h5 content does appear in the page table of contents.