# Headings

Headings in sitemd are standard markdown — `#` through `######` — with auto-generated anchor IDs and built-in SEO handling for multiple H1s.

## How are heading IDs generated?

Every heading automatically gets a URL-friendly `id` attribute derived from its text. `## Getting Started` becomes `id="getting-started"`. Duplicate IDs within the same page are resolved by appending a number (`-2`, `-3`, etc.).

Use these IDs as anchor links:

```markdown
[Jump to section](#getting-started)
[See the themes docs](/docs/themes#custom-colors)
```

Cross-page anchors load the page and scroll to the target automatically.

## What happens with multiple H1s?

Write as many `# headings` as your design needs. The engine always renders the first as a true `<h1>`. All subsequent `# headings` render as `<h2>` elements with identical H1 styling — same size, same weight, same visual appearance — so the page looks exactly as intended.

```markdown
# Hero Section

Some intro text.

# Features

More content here.

# Pricing

Even more content.
```

This renders in HTML as:

```html
<h1 id="hero-section">Hero Section</h1>
<h2 class="h1-style" id="features">Features</h2>
<h2 class="h1-style" id="pricing">Pricing</h2>
```

The `h1-style` class preserves the visual appearance of H1. Subheadings (`##`, `###`, etc.) under these sections are left completely untouched.

Search engines see exactly one `<h1>` — the primary topic anchor they need. The [SEO audit](/docs/seo-audit) treats this as a passing page.

## What if I don't want a visible H1?

Use a [`hidden:`](/docs/hidden-content) block to add an H1 that search engines index but visitors don't see:

```markdown
hidden:
# Page Title for SEO
/hidden

The rest of your page content here.
```

The [SEO audit](/docs/seo-audit) recognizes hidden H1s as valid and won't flag the page.

## Heading reference

| Markdown | Rendered tag | Notes |
|---|---|---|
| `# Heading` (first) | `<h1>` | Primary SEO heading |
| `# Heading` (2nd+) | `<h2 class="h1-style">` | Visually identical to H1 |
| `## Heading` | `<h2>` | Main sections |
| `### Heading` | `<h3>` | Subsections |
| `#### Heading` | `<h4>` | Sub-subsections |
| `##### Heading` | `<h5>` | Rarely needed |
| `###### Heading` | `<h6>` | Rarely needed |

## Related

- [Pages & Content](/docs/pages-and-content) — full page authoring reference
- [Hidden Content](/docs/hidden-content) — visually hidden headings for SEO
- [SEO Audit](/docs/seo-audit) — heading checks and scoring
- [Content Alignment](/docs/content-alignment) — center or right-align heading blocks