# Headings

> Generated heading IDs, custom anchors and the page's table of contents.

Headings automatically get anchor IDs for linking.

## Auto-generated IDs

**HTML**

```html
<h2>My Heading</h2>
```

**Markdown**

```md
## My Heading
```

Renders as `<h2 id="my-heading">My Heading</h2>`. Every `<h2>` to `<h6>` without an `id` gets one from its text: lowercased, with every run of other characters turned into a hyphen. A slug already taken on the page gets a number, `my-heading-2`.

## Custom Heading IDs

Give the heading its own `id` and htmlpress keeps it:

**HTML**

```html
<h2 id="custom-id">My Heading</h2>
```

**Markdown**

```md
## My Heading {#custom-id}
```

Link to it with `#custom-id`. Ids written in the page are reserved first, so a generated slug never takes one a link elsewhere points at. Give a heading an `id` only when a link needs it fixed. This heading itself uses `id="custom-ids"`.

## Heading Levels

Use `<h2>` to `<h4>` for content structure. The `<h1>` is reserved for the page title.

`<h2>` to `<h4>` appear in the table of contents; `<h5>` and `<h6>` are styled and linkable but not listed.

## TOC Control

The table of contents lists the page's `<h2>`, `<h3>` and `<h4>`, highlighting the one in view. Headings inside a callout, card, steps or tabs component stay out of it, so a component's own headings never crowd the page's outline.

`data-toc="false"` keeps a heading off the table of contents while it stays on the page; `data-toc="only"` lists a heading there without showing it, a landmark for a stretch of the page that has no visible title. Any other value fails the build.

**HTML**

```html
<h2 data-toc="false">Shown, not listed</h2>
<h2 data-toc="only">Listed, not shown</h2>
```

**Markdown**

```md
## Shown, not listed [!toc]

## Listed, not shown [toc]
```

## Anchor Links on Hover

Every `<h2>` to `<h6>` with an id shows a `#` link to itself on hover, to copy the anchor URL for sharing.

## Inline Table of Contents

An `<htmlpress-toc>` written in the page is filled with the page's table of contents, framed as a card: down to its `<h4>`s by default, only the `<h2>`s with `max-level="2"`, down to the `<h3>`s with `max-level="3"`. A page without headings gets none.

**HTML**

```html
<htmlpress-toc max-level="2"></htmlpress-toc>
```

**Markdown**

```md
::toc{maxLevel="2"}
```