Use standard Markdown # syntax for most headings. Each level renders through the Heading component with a slugified id and a hover anchor link. Use the <Heading> component only when Markdown syntax is not practical.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6The visible page title comes from frontmatter title, not from a Markdown # heading in the body. Set title and description in frontmatter; do not duplicate the page name as an h1 in the content.
When showPageTitle is enabled in frontmatter or site config, the page title renders as an h1 above the body content.
Do not repeat the frontmatter title as # Page title in the body. That creates a duplicate heading and can confuse the table of contents.
Markdown headings from # through ###### are parsed from the page source and assigned slugified id values. Those IDs power in-page anchor links and the On this page table of contents.
Slugification lowercases the heading text, removes non-alphanumeric characters, and replaces spaces with hyphens. Duplicate titles on the same page receive numeric suffixes (-1, -2, and so on). Headings inside fenced code blocks are ignored.
Hover a heading to reveal the anchor link. Every Markdown heading level receives an anchor when rendered.
The table of contents lists Markdown headings only. Manual <Heading> components are not extracted.
By default, headings from h2 through h3 appear in the table of contents. The minimum depth is fixed at h2; the maximum depth follows content.headerDepth in docs.json (defaults to 3).
| Setting | Default | Effect |
|---|---|---|
| Minimum depth | 2 (h2) | h1 headings are excluded from the table of contents |
| Maximum depth | content.headerDepth (3) | Deepest heading level included in the table of contents |
{
"content": {
"headerDepth": 3
}
}Increase headerDepth to include deeper levels, for example 4 includes h4 headings, 5 includes h5, and 6 includes h6.
When Markdown syntax is unavailable, for example inside a component that does not parse Markdown, use <Heading> directly.
<Heading type="h2" id="custom-section">Custom section</Heading>Set id when you need a stable anchor link. Without id, the heading renders without a hover anchor. Manual headings are never added to the table of contents, even when id is set.
The heading level to render. Must be one of h1 through h6.
Controls typography and spacing. Match the semantic level of the content: use h2 for major sections, h3 for subsections, and so on.
A stable anchor identifier for the heading. When set, the heading shows a hover anchor link pointing to #id.
Omit id when you do not need a linkable target. Manual headings with an id still do not appear in the table of contents.
Standard HTML heading attributes (such as className) are forwarded to the underlying element.
| Condition | Result |
|---|---|
Markdown # … ###### heading | Slugified id, hover anchor link, included in table of contents when depth is in range |
<Heading> with id | Renders heading with hover anchor link; not included in table of contents |
<Heading> without id | Renders heading without hover anchor link; not included in table of contents |
| Duplicate heading titles | Slugs receive numeric suffixes (-1, -2, …) |
| Heading inside a code fence | Ignored for IDs and table of contents |
- Components overview: when to use headings with other layout components
- docs.json:
content.headerDepthand other content settings