> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# Overview 页

Overview 页用于展示某个目录下所有文章的概览，会自动从侧边栏提取信息并生成分组内容。

## 用法

在目录的 `index.md` 中配置 `overview: true` 即可开启：

```md title="api/index.md"
---
overview: true
title: API Overview
---

这是 API 的概览页面。
```

Overview 页会自动读取当前目录的[侧边栏配置](https://rspress.rs/zh/guide/basic/auto-nav-sidebar.md)，提取各文章的标题生成分组卡片。

## 示例

假设有如下目录结构和 `_meta.json` 配置：

```tree
docs
└── api
    ├── _meta.json
    ├── index.md        <-- overview: true
    ├── config
    │   ├── _meta.json
    │   ├── basic.mdx
    │   └── theme.mdx
    └── runtime
        ├── _meta.json
        ├── hooks.mdx
        └── context.mdx
```

```mdx title="api/index.md"
---
overview: true
title: API Overview
---

这是 API 的概览页面。
```

```json title="api/_meta.json"
[
  { "type": "file", "name": "index", "label": "API Overview" },
  { "type": "dir", "name": "config", "label": "Config" },
  { "type": "dir", "name": "runtime", "label": "Runtime" }
]
```

生成的 Overview 页面如下：


# Overview 页

## Config

### [basic](/#)

- [title](/##title)
- [description](/##description)

### [theme](/#)

- [darkMode](/##dark-mode)
- [footer](/##footer)
## Runtime

### [hooks](/#)

- [usePage](/##use-page)
- [useSite](/##use-site)

### [context](/#)

- [DataContext](/##data-context)
- [ThemeContext](/##theme-context)

## 配置

### overviewHeaders

控制在 Overview 页中展示的标题级别，默认为 `[2]`（即只展示 h2 标题）。

可以在 `_meta.json` 中配置：

```json title="_meta.json"
[
  {
    "type": "file",
    "name": "component",
    "overviewHeaders": [2, 3]
  }
]
```

也可以在文章的 frontmatter 中配置：

```md title="component.mdx"
---
overviewHeaders: [2, 3]
---
```

### 嵌套 Overview 页

子目录同样可以有自己的 Overview 页，只需在子目录的 `index.md` 中配置 `overview: true`：

```tree
docs
└── api
    ├── index.md         <-- overview: true
    └── theme
        ├── index.md     <-- overview: true (子 Overview 页)
        ├── component.mdx
        └── utils.mdx
```

## 自定义

如果需要完全自定义 Overview 页的内容，有以下两种方案：

### 方案一：通过自定义主题修改样式

通过[自定义主题](https://rspress.rs/zh/guide/basic/custom-theme.md)来修改 [OverviewGroup](https://rspress.rs/zh/ui/layout-components/overview-group.md) 组件的样式，同时继续使用 Overview 页的内置功能：

```mdx title="index.mdx"
---
overview: true
---
```

### 方案二：完全自定义页面内容

使用 [OverviewGroup](https://rspress.rs/zh/ui/layout-components/overview-group.md) 组件并通过 `pageType: doc-wide` 调整页面布局，自行定义页面内容：

```mdx title="index.mdx"
---
pageType: doc-wide
---

# My custom overview page

import { OverviewGroup } from '@rspress/core/theme';

<OverviewGroup
  group={{
    name: 'Custom Group',
    items: [
      {
        text: 'Page Title',
        link: '/path/to/page',
        headers: [
          { id: 'section-1', text: 'Section 1', depth: 2 },
          { id: 'section-2', text: 'Section 2', depth: 2 },
        ],
      },
    ],
  }}
/>
```