Table of contents

Write headings that create a useful page outline.

The table of contents comes from page headings. Clear headings make long docs easier to scan and easier to share.

Heading rules

Follow these rules so the page outline and table of contents stay clean.

  • Do not write an H1 inside MDX content.
  • Use ## for main sections.
  • Use ### for details inside a section.
  • Avoid clever headings that hide the actual task.

Why no H1

The docs layout already renders the page title from metadata. A second H1 creates duplicate hierarchy and makes the page outline less useful.

Example outline

This outline shows how a page can use nested headings without adding a duplicate H1.

## Create the post folder

### Add the article file

### Add the cover image

## Review metadata

### Check the description

TOC quality

A strong table of contents should let readers understand the page without reading every paragraph.