# 文章分区
> 将站点划分为多个分区，每个分区有自己的标签页和导航。
分区是站点的一部分，例如指南和 API 参考，它有自己的 URL 前缀、自己的标签页和自己的导航：当打开其中某个页面时，侧边栏以及上一页、下一页链接只显示该分区的页面。Htmlpress 提供以下几种分区类型：
- **Article**：默认类型。某个前缀下的页面，在侧边栏中按文件夹分组。
- **Custom**：只是一个指向某个 URL 的标签页。
- **Blog**：带日期的文章，最新的在前，带有标签页面和 RSS 订阅源。
- **Changelog**：Markdown 变更日志中每个版本一页。
## 基本用法
```yaml
site: https://example.com
sections:
- title: Guide
prefix: /
- title: API
prefix: /api/
siteTitle: API Reference
- title: GitHub
type: custom
url: https://github.com/datisthq/htmlpress
```
省略 `sections` 时，所有页面渲染在同一个导航中，适合小型站点。
## 通用字段
每个分区都接受：
| 字段 | 默认值 | 用途 |
| ----------------- | ----------------- | ------------------------------------------------------------------------- |
| `title` | 无，必填 | 标签页的名称，也是该分区在 `llms.txt` 中的分组名。 |
| `type` | `article` | `article` 拥有页面；`custom` 只是一个指向其 `url` 的标签页。 |
| `prefix` | 无，`article` 必填 | 其页面共享的文件夹路径，以 `/` 开头和结尾（`/`、`/api/`）。标签页指向位于该前缀的页面，否则指向该分区的第一个页面。 |
| `url` | 无，`custom` 必填 | `custom` 标签页指向的地址。 |
| `position` | `header` | `header` 表示位于页眉链接旁的标签页， `sidebar` 表示位于侧边栏页面上方的条目。 |
| `icon` | 无 | 标题前的[内置图标](/zh/authoring/rich-elements/#图标)，例如 `book-open`。 |
| `siteTitle` | 站点的 `title` | 打开该分区的页面时品牌区显示的标题。 |
| `siteLink` | `/` | 打开该分区的页面时品牌区链接的地址。 |
| `siteDescription` | 站点的 `description` | 该分区中没有自身描述的页面所用的描述，也显示在品牌区下方。 |
| `source` | 无，`changelog` 必填 | 要拆分的 Markdown 变更日志，路径相对于项目；它必须位于项目内，且不能是点文件。也可以是 GitHub 仓库的 URL，从其发布版本构建。 |
| `version` | `false` | 用于 `changelog`：在标题旁显示最新版本。 |
其他任何字段都会报错；没有 `prefix` 的 `article` 分区、不以 `/` 开头和结尾的前缀，或没有 `url` 的 `custom` 分区，同样会报错。在手机上，所有分区，无论位于页眉还是侧边栏，都会列在侧边栏中。
## Article 分区
普通文档，也是默认类型：你可以完全省略 `type`。
```yaml
- title: Guide
prefix: /guide/
```
在分区内部，侧边栏按文件夹嵌套其页面，深度不限。根目录下的页面不分组，每个文件夹在其父文件夹的分组内拥有自己的可折叠分组，名称取自其 `index.html` 的标题，否则取文件夹名：
- introduction.html
- guides
- index.html
- install.html
- deploy.html
- reference
- index.html
- cli.html
- api
- index.html
- auth.html
`guides/index.html` 在 `/guides/` 提供，是该分组自己的页面，同时在面包屑中为该文件夹命名。没有 `sections` 时，整个站点都按这种方式分组。
`custom` 分区不拥有页面。当其 `url` 为内部地址，且指向当前打开的页面或其上层文件夹时（`/` 仅在首页时），它的标签页会被标记为当前；外部 URL 永远不会。
```yaml
- title: Blog
type: custom
url: https://blog.example.com
```
## Blog 分区
`blog` 分区的页面是文章：日期由 `` 指定，作者由 `` 指定，标签由 `` 指定。上一页、下一页链接按最新在前的顺序列出它们。侧边栏链接到全部文章、最新的五篇、RSS 订阅源（需设置 `site`）和每个标签；变更日志的侧边栏同样链接到全部发布版本和最新的五个。构建还会添加：
- 位于前缀处、列出所有文章的索引，除非该分区有自己的 `index.html`；
- 前缀下 `tags//` 处的每个标签一页；
- 前缀下 `rss.xml` 处的 RSS 订阅源，从每个页面的 head 中链接，在设置了 `site` 时生成，因为订阅源使用绝对链接。
```yaml
- title: Blog
type: blog
prefix: /blog/
```
## Changelog 分区
`changelog` 分区在每个 `##` 标题处拆分其 `source`，在前缀下的 `/` 处为每个版本生成一页，按文件中的顺序最新在前，另加一个列出所有版本的索引。release-please 风格的标题 `## [0.2.0](…) (2026-10-01)` 给出版本号及其日期；该版本的 `###` 标题成为其小节。设置 `version: true` 时，标签页会显示最新版本。
```yaml
- title: Changelog
type: changelog
prefix: /changelog/
source: CHANGELOG.md
version: true
```
若 `source` 指向一个 GitHub 仓库，如 `https://github.com/acme/tool`，则改为每个发布版本构建一个页面：以其标签作为版本，并包含发布日期、发布说明和一个“在 GitHub 上查看”链接。发布说明中的原始 HTML 会显示为文本，因此发布版本无法向站点添加脚本。构建会从 GitHub API 读取前 100 个发布版本，若环境中设置了 `GITHUB_TOKEN` 则使用它，并把结果缓存在 `.htmlpress/cache/`；之后的构建会重新验证缓存，并在无法连接 GitHub 时回退到缓存。没有缓存时，请求失败会导致构建失败。
## 排序与匹配
页面 URL 按最长前缀优先的规则匹配到分区。给定 `/api/v2/auth/` 以及前缀为 `/` 和 `/api/` 的分区，该页面会被放入 `/api/`。由于前缀是文件夹路径，`/guide/` 永远不会匹配 `/guides/`。不属于任何分区的页面组成另一个独立部分，拥有自己的导航。
`llms.txt` 也按分区对链接分组，顺序与配置一致，不属于任何分区的页面放在最后的 "Other" 下；没有 `sections` 时，按顶层文件夹分组。
在一个导航中，页面属于其所在文件夹 `index.html` 的分组，该索引页属于其父文件夹的分组：`guides/cli/run.html` 位于 "Guides" 内的 `cli` 分组中。没有 `index.html` 的文件夹不构成分组，其页面位于顶层。页面在同级之间按 `` 排序：根目录的 `index.html` 始终排在最前，随后是按升序排列的 0 及以上的 order，然后是按路径排序的无 order 页面，最后是负 order，`-1` 排在最末。分组位于其 `index.html` 排序所在的位置，因此给它设置 order 即可放置整个分组。翻页器从上到下遍历侧边栏，每个分组的索引页排在其页面之前。
根目录下的 `404.html` 不会出现在侧边栏中；它是托管服务在 URL 缺失时显示的页面，没有该文件的项目会获得一个内置的 "Page not found" 页面。
## 另请参阅
- [外部链接](/zh/customization/external-links/)：在分区标签页旁添加链接。
- [Frontmatter](/zh/authoring/frontmatter/)：驱动分区内容的 `` 和 `<meta name="order">`。