---
title: Table of contents
description: 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.

```tsx
## 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.