# 标题

> 自动生成的标题 ID、自定义锚点和页面目录。

标题会自动获得用于链接的锚点 ID。

## 自动生成的 ID

**HTML**

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

**Markdown**

```md
## My Heading
```

渲染为 `<h2 id="my-heading">My Heading</h2>`。每个没有 `id` 的 `<h2>` 到 `<h6>` 都会根据其文本获得一个 ID：转为小写，并把每段其他字符替换为一个连字符。若该 slug 在页面上已被占用，则会追加编号，如 `my-heading-2`。

## 自定义标题 ID

为标题设置自己的 `id`，htmlpress 会保留它：

**HTML**

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

**Markdown**

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

用 `#custom-id` 链接到它。页面中手写的 ID 会被优先保留，因此生成的 slug 永远不会占用其他地方链接所指向的 ID。只有当某个链接需要固定的 ID 时，才为标题设置 `id`。本标题本身就使用了 `id="custom-ids"`。

## 标题级别

使用 `<h2>` 到 `<h4>` 来组织内容结构。`<h1>` 保留给页面标题。

`<h2>` 到 `<h4>` 会出现在目录中； `<h5>` 和 `<h6>` 会应用样式并可被链接，但不会列出。

## 目录控制

目录列出页面的 `<h2>`、`<h3>` 和 `<h4>`，并高亮当前可见的那个。提示框、卡片、步骤或标签页组件内的标题不会进入目录，因此组件自身的标题永远不会挤占页面的大纲。

`data-toc="false"` 让标题留在页面上但不进入目录；`data-toc="only"` 则把标题列入目录但不在页面上显示，用作页面中没有可见标题的一段内容的地标。其他任何值都会导致构建失败。

**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]
```

## 悬停时的锚点链接

每个带 ID 的 `<h2>` 到 `<h6>` 在悬停时都会显示一个指向自身的 `#` 链接，便于复制锚点 URL 进行分享。

## 内联目录

写在页面中的 `<htmlpress-toc>` 会被填入页面目录，并以卡片形式呈现：默认包含 到 `<h4>` 为止的标题，`max-level="2"` 只保留 `<h2>`，`max-level="3"` 则包含到 `<h3>`。没有标题的页面不会生成目录。

**HTML**

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

**Markdown**

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