文章分区

更新于 2026年11月1日

分区是站点的一部分，例如指南和 API 参考，它有自己的 URL 前缀、自己的标签页和自己的导航：当打开其中某个页面时，侧边栏以及上一页、下一页链接只显示该分区的页面。Htmlpress 提供以下几种分区类型：

Article：默认类型。某个前缀下的页面，在侧边栏中按文件夹分组。
Custom：只是一个指向某个 URL 的标签页。
Blog：带日期的文章，最新的在前，带有标签页面和 RSS 订阅源。
Changelog：Markdown 变更日志中每个版本一页。

基本用法

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`	无	标题前的内置图标，例如 `book-open`。
`siteTitle`	站点的 `title`	打开该分区的页面时品牌区显示的标题。
`siteLink`	`/`	打开该分区的页面时品牌区链接的地址。
`siteDescription`	站点的 `description`	该分区中没有自身描述的页面所用的描述，也显示在品牌区下方。
`source`	无，`changelog` 必填	要拆分的 Markdown 变更日志，路径相对于项目；它必须位于项目内，且不能是点文件。也可以是 GitHub 仓库的 URL，从其发布版本构建。
`version`	`false`	用于 `changelog`：在标题旁显示最新版本。

其他任何字段都会报错；没有 prefix 的 article 分区、不以 / 开头和结尾的前缀，或没有 url 的 custom 分区，同样会报错。在手机上，所有分区，无论位于页眉还是侧边栏，都会列在侧边栏中。

Article 分区

普通文档，也是默认类型：你可以完全省略 type。

- 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 永远不会。

- title: Blog
  type: custom
  url: https://blog.example.com

Blog 分区

blog 分区的页面是文章：日期由 <meta name="date"> 指定，作者由 <meta name="author"> 指定，标签由 <meta name="keywords"> 指定。上一页、下一页链接按最新在前的顺序列出它们。侧边栏链接到全部文章、最新的五篇、RSS 订阅源（需设置 site）和每个标签；变更日志的侧边栏同样链接到全部发布版本和最新的五个。构建还会添加：

位于前缀处、列出所有文章的索引，除非该分区有自己的 index.html；
前缀下 tags/<tag>/ 处的每个标签一页；
前缀下 rss.xml 处的 RSS 订阅源，从每个页面的 head 中链接，在设置了 site 时生成，因为订阅源使用绝对链接。

- title: Blog
  type: blog
  prefix: /blog/

Changelog 分区

changelog 分区在每个 ## 标题处拆分其 source，在前缀下的 <version>/ 处为每个版本生成一页，按文件中的顺序最新在前，另加一个列出所有版本的索引。release-please 风格的标题 ## [0.2.0](…) (2026-10-01) 给出版本号及其日期；该版本的 ### 标题成为其小节。设置 version: true 时，标签页会显示最新版本。

- 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 的文件夹不构成分组，其页面位于顶层。页面在同级之间按 <meta name="order"> 排序：根目录的 index.html 始终排在最前，随后是按升序排列的 0 及以上的 order，然后是按路径排序的无 order 页面，最后是负 order，-1 排在最末。分组位于其 index.html 排序所在的位置，因此给它设置 order 即可放置整个分组。翻页器从上到下遍历侧边栏，每个分组的索引页排在其页面之前。

根目录下的 404.html 不会出现在侧边栏中；它是托管服务在 URL 缺失时显示的页面，没有该文件的项目会获得一个内置的 "Page not found" 页面。

另请参阅

外部链接：在分区标签页旁添加链接。
Frontmatter：驱动分区内容的 <title> 和 <meta name="order">。

用 ❤ 和 Htmlpress 构建