版本管理

Htmlpress 没有专门的版本管理功能：它现有的构建模块已经能覆盖两种常见形式。根据版本之间的差异程度来选择：

• 一个站点，每个版本一个分区：少数几个版本，其文档位于同一个分支上。
• 每个版本一次部署：长期维护的主版本，各自在自己的分支上维护。

大多数项目只需保留最新文档和上一个主版本。如果旧版本只需要发布说明，一个 变更日志分区 就足够了。

每个版本一个分区

把每个旧版本的页面放在单独的文件夹中。当前文档保留在 /，每个旧版本成为一个分区：

title: Acme
sections:
  - title: Docs
    prefix: /
  - title: v1
    prefix: /v1/
    icon: archive
    siteTitle: Acme v1

最长前缀匹配会把每个 /v1/… 页面路由到 v1 分区，因此它拥有自己的侧边栏，而站点其余部分保留当前文档。siteTitle 会在该分区内重新设置 logo 旁的品牌标题，让读者始终知道自己正在看哪个版本。设置 position: sidebar 可以让版本标签页不出现在页眉中。

要在旧页面上提醒读者，可以在每个页面开头放一个标注框：

<htmlpress-callout type="warning">
  <p>You are reading the docs for v1. <a href="/getting-started/">See the latest version</a>.</p>
</htmlpress-callout>

:::warning
You are reading the docs for v1. [See the latest version](/getting-started/).
:::

需要注意：

• 搜索会索引整个站点，因此结果中包含所有版本的页面。
• 为每个版本复制一个文件夹会产生重复内容；请冻结旧文件夹，仅在必要时修复。

每个版本一次部署

当每个主版本都位于自己的分支上（main、v1……）时，把每个分支构建为独立站点，并通过各自的地址提供：子域名（v1.docs.example.com），或借助 base 使用子路径（docs.example.com/v1/）。

site: https://docs.example.com
base: /v1/
title: Acme v1
banner: You are reading the v1 docs · <a href="https://docs.example.com/">Go to the latest →</a>

htmlpress start 和 preview 在相同的基础路径下提供站点，因此分支的预览效果与部署后完全一致。可以用一个 custom 分区或一个页眉链接把各个部署相互连接起来，充当版本切换器：

sections:
  - title: Docs
    prefix: /
  - title: v1
    type: custom
    url: https://docs.example.com/v1/
    icon: archive

每个部署都有自己的搜索索引、站点地图和 llms.txt，因此各版本绝不会混在一起。代价是每个维护中的分支都需要一次构建和一个 CI 任务；各托管平台的配置请参见 Deployment。大多数托管平台开箱即支持把分支部署到各自的 URL。

另请参阅

• 文章分区：分区类型、前缀和匹配。
• 站点元数据：上文用到的 banner、title 和 site 字段。