多版本

产品有多个受支持版本时，文档通常也要分版本。主题提供两项功能：顶栏的版本切换菜单，与旧版本站点上的归档提示横幅。部署布局由站点决定：主题不做跨版本的单次构建，每个版本是一次独立的 Hugo 构建。

版本切换菜单

在 params.versions 里列出要出现在菜单里的版本。这个列表非空时，顶栏工具区出现一个分支图标的菜单，页脚最底层栏出现同样内容的纯图标向上菜单。

params:
  # 当前站点是哪个版本
  version: v2.1
  # 菜单的无障碍名称；底栏触发器仍只显示图标
  version_menu: v2.1
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v2.0
      url: https://v2-0.docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com

菜单项默认显示 version 的值，写了 name 就显示 name。当前项标成选中态，判定方式是条目的 version 等于 params.version，或者条目的 url 等于站点的 baseURL，两者满足其一即可。

没写 url 的条目显示为不可点击的灰项，可用作分节标题；name: '---' 是一条分隔线（分隔线上写 url 会告警）。name 支持行内 Markdown：

params:
  versions:
    - name: '**当前版本**'
    - version: v2.1
      url: https://docs.example.com
    - name: '---'
    - name: '**历史版本**'
    - version: v1.9
      url: https://v1-9.docs.example.com

同一份列表也是命令面板里「切换版本」的数据来源，菜单与面板不会不一致。

逐页跳转的取舍

version_menu_pagelinks: true 会把当前页面的路径拼到目标版本的 URL 后面，读者切换版本时 停在同一篇文档。

代价是目标版本不一定有这个页面：文档结构在版本间会演进，旧版本没有新增的页面，读者切换过去就是 404。本站关闭这个选项。

单个条目可以覆盖全局设置：

params:
  version_menu_pagelinks: true
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com
      pagelinks: false # 这一版结构差异大，只跳首页

归档横幅

不再维护的旧版本站点上，向读者说明这是一份快照：

params:
  archived_version: true
  version: v1.9
  url_latest_version: https://docs.example.com

archived_version: true 时，每个文档页与书籍页正文顶部出现一条横幅，写明当前版本已不再积极维护，并给出指向 url_latest_version 的链接。文案随站点语言本地化，无需自行编写；version 是横幅里显示的版本号。

横幅只出现在文档与书籍页面上，博客和落地页没有。

params.version 与 params.versions 的区别

两个键名字相近，职责不同：

• params.versions 是 一张跨站点的清单：菜单里能跳到哪些版本，各自的地址是什么。它描述的是其它站点。
• params.version 是当前这次构建自己的版本标识。它决定菜单里哪一项被标成选中、归档横幅里显示什么版本号，data/download/*.yaml 没写 version 时也以它兜底（见发布与下载页）。

它不一定是 Git 引用。需要一个能解析的发布 tag（例如安装命令里引用的那个）时，另设一个自己的参数，不要复用 params.version。这两个键的完整定义在配置总览。

多版本部署布局

每个版本是一次独立构建：从对应的 Git 分支或 tag 检出内容，用那一版自己的 hugo.yml 构建，产物发布到对应地址。当前版本的站点把 versions 列全，旧版本的站点在列全之外再加上归档横幅。

验证

1. 构建后确认版本菜单进了页面：

   grep -c 'nav-version-menu' public/zh/docs/customize/versions/index.html

   params.versions 为空或未配置时，菜单整个不生成。

2. 看当前版本有没有被标成选中：

   grep -o 'nav-hover-menu__option is-active[^>]*' public/index.html

   一条都没有，说明 params.version 与 versions 里的 version 字段对不上，或者 baseURL 与该条目的 url 不一致（注意结尾斜杠）。

3. 逐个访问菜单里的链接。开启 version_menu_pagelinks 时，在一篇旧版本不存在的文档上试一次，确认落点可以接受。

4. 归档站点上打开任意文档页，横幅应该在正文最上方，语言与站点一致，链接指向最新版本。

5. 按 ⌘/Ctrl + K 打开命令面板，「切换版本」列出的应该是同一份清单。

相关

• 导航与菜单 — 版本菜单在顶栏与侧栏里的位置
• 命令面板 — 面板里的「切换版本」
• 发布上线 — baseURL、子路径与多目标发布
• 发布与下载页 — 用 params.version 兜底的下载数据
• 配置总览 — version / versions / archived_version 的完整定义