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:
- How to enable or disable the TOC globally
- How to override TOC settings for any specific page(s)
- How content is sourced for the TOC
To enable the TOC on all pages, add this to the
toc: enable: true
The TOC is disabled by default. If you want to disable it explicitly, add this to the
toc: enable: false
You can control the maximum depth of the TOC. The maximum depth refers to how many heading levels will be rendered in the TOC (
Set it using a numeric value corresponding to the heading level.
The default value in the portal is
4, meaning it will display
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.
toc: enable: true maxDepth: 3
enableToc: true tocMaxDepth: 3
You can override the global setting in the front matter of any Markdown or MDX page.
In the following example, the TOC will be hidden on the page even if it is enabled globally.
--- seo: title: Markdown example description: GitHub-Flavored Markdown example toc: enable: false --- Example text
--- title: Markdown example description: GitHub-Flavored Markdown example enableToc: false --- Example text
Open and close the front matter appropriately using three or more dashes
---, or the front matter will be invalid and display as text on your page.
The TOC content comes from the
h4 tags on the page.
It is also sourced from any additional
h1 tags except the opening
h3 content will appear indented.
h4 content will appear further indented.
h5 content will not appear in the page table of contents.