版本文档

在 GitHub Docs 中，我们提供的文档版本能够反映 GitHub 各主要产品在 UI 和功能上的差异。贡献者可以使用版本语法将内容限定在特定的产品范围内。

版本语法允许读者手动选择适用于其所使用产品的文档版本。GitHub Docs 的 URL 也可以包含版本信息，这样从一个版本的文档指向另一个版本时，能够直接将读者送到其使用的产品对应的文档页面。

如何以及在哪里进行版本控制

GitHub Docs 中的内容版本控制采用单源方式，以避免重复并保持正文 DRY。对于文章，您在 Markdown 文件的 YAML 元数据中为其应用版本控制，然后在文件正文中使用条件语句指示站点根据读者选择的版本显示相应的文本。单源方式与为每个版本分别创建独立文件形成对比。

GitHub Docs 有两种版本语法。

• YAML：最常用于 content/ 中 Markdown 文件的 YAML front matter，也常用于 data/ 中的各种 YAML 文件。用于指明整个内容片段的版本。

  versions:
    PRODUCT: 'VERSIONS'
    PRODUCT: 'VERSIONS'
    ...
  

  下面的示例展示了针对 Free、Pro、Team 以及所有 GitHub Enterprise Server 版本的内容版本控制。

  versions:
    fpt: *
    ghes: *
  

• Liquid：用于 content/ 与 data/reusables/ 中的 Markdown 文件、data/variables/ 中的 YAML 变量字符串，或 data/glossaries/external.yml 中的字符串。用于指明当读者为已在 YAML front matter 中定义多版本的内容选择某个版本时，应显示哪段文字。

  • 基于产品的版本控制

    {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
    

  • 基于特性的版本控制

    {% ifversion FEATURE-NAME %} ... {% endif %}
    

关于 GitHub 的不同版本

我们为 GitHub 各计划（包括 GitHub Enterprise Cloud 与 GitHub Enterprise Server）的用户提供带版本的文档。如果同一页面在站点上存在多个版本，读者可在页面顶部的版本选择器中挑选所需版本。

GitHub.com

GitHub.com 文档有两种可能的版本

Free、Pro 或 Team 计划

针对 GitHub.com 上的 Free、Pro、Team 计划，请使用 free-pro-team@latest。其简称为 fpt。

GitHub Enterprise Cloud

针对 GitHub Enterprise Cloud，请使用 enterprise-cloud@latest。其简称为 ghec。

GitHub Enterprise Server

GitHub Enterprise Server 的文档拥有多个版本，可分为两类：受支持的发布（我们一次最多支持四个）以及即将停用的发布（这些版本在 Docs 站点上不提供链接，但我们会永久保留其“冻结”快照，若您知晓 URL 仍可访问）。请参阅 lib/enterprise-server-releases.ts 获取完整列表。

这些版本的命名形式为 enterprise-server@<release>，简称为 ghes。在 Liquid 条件语句中，我们可以指定范围，例如 ghes > 3.0。更多信息请参见 使用 Liquid 条件运算符进行版本控制。

YAML frontmatter 中的版本控制

您可以在文件的 frontmatter 中使用 versions 属性来定义文章适用于哪些产品。索引文件必须包含 versions 属性，但其版本会自动依据子页面的版本进行推导。

例如，下面的 YAML frontmatter 将为 GitHub Enterprise Server 2.20 及以上版本以及 Free、Pro、Team 计划提供该文章。

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

下面的示例将为所有受支持的 GitHub Enterprise Server 版本提供该文章。

title: Downloading your license
versions:
  ghes: '*'

您还可以为一段版本范围制定版本控制。下面的示例仅为 Free、Pro、Team、GitHub Enterprise Cloud 以及 GitHub Enterprise Server 3.1 与 3.2 这几个版本提供该页面。

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

使用 Liquid 条件运算符进行版本控制

我们使用 Liquid 模板语言（具体而言，是 此 Node.js 移植版）以及自定义的 {% ifversion ... %} 标签来创建文档的不同版本。

如果在页面的 YAML frontmatter 中的 versions 键下定义了多个产品，您可以在 Markdown 中使用 ifversion/else（或 ifversion/elsif/else）条件运算符来控制站点在特定产品下渲染的内容。例如，某功能在 GitHub.com 上的选项比在 GitHub Enterprise Server 上多，您可以在 frontmatter 中通过 versions 为该功能设定版本，并使用 Liquid 条件在 GitHub.com 上描述额外选项。

比较运算符

对于没有编号发行版的版本（如 fpt 和 ghec），您有两种写法：

• {% ifversion ghec %}
• {% ifversion not ghec %}

对于有编号发行版的版本（目前仅 ghes），您同样可以针对“在所有发行版均可用”或“在所有发行版均不可用”的内容使用相同写法。

• {% ifversion ghes %}
• {% ifversion not ghes %}

若需标记仅在特定发行版可用（或不可用）的内容，可使用以下运算符：

运算符	含义	示例
=	等于	{% ifversion ghes = 3.0 %}
>	大于	{% ifversion ghes > 3.0 %}
<	小于	{% ifversion ghes < 3.0 %}
!=	不等于	{% ifversion ghes != 3.0 %}（范围内请勿使用 not）

GitHub Docs 不支持 Liquid 运算符 ==、>= 与 <=。

逻辑运算符

当所有操作数必须为真才能成立时，使用 and。

{% ifversion ghes > 2.21 and ghes < 3.1 %}

当至少有一个操作数为真即可成立时，使用 or。

{% ifversion fpt or ghes > 2.21 %}

不要使用 && 或 ||。Liquid 并不识别它们，内容将在相应版本中无法渲染。

空白控制

在列表中使用 Liquid 条件时，可使用 空白控制字符来防止插入换行符或其他空白，从而破坏列表渲染。

在标签左侧、右侧或两侧均可添加连字符（-），表示该侧不应出现换行或其他空白。

{%- ifversion fpt %}

例如，要对某一步骤进行版本控制，若将 Liquid 代码直接写在上一行的末尾，如下所示：

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

您可以将 Liquid 代码单独放在一行，并使用空白控制去除其左侧的换行符。这使得阅读源文件更加轻松，同时不影响列表的渲染。

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

关于基于特性的版本控制

在记录任何新变更或新功能时，请使用基于特性的版本控制。

极少数功能和变更只会适用于单一产品。大多数功能首先在 GitHub.com（包括 GitHub Enterprise Cloud）出现，随后会逐步推广至所有产品。一般而言，变更从 GitHub.com 流向 GitHub Enterprise Server。

基于特性的版本控制提供了具名的“特性标记”，简化了文档的维护与版本管理。您可以使用同一个特性名称（或“标记”）在整个内容中进行分组和版本控制。当同一特性在更多产品上线时，只需在 data/features/ 下的文件中修改一次 YAML 版本信息即可。

管理特性

每个特性均通过 data/features/ 中的独立 YAML 文件进行管理。

要创建新特性，首先在该目录下新建一个以特性名称命名的 YAML 文件。例如，要添加名为 meow 的特性，应创建 data/features/meow.yml。

在该 YAML 文件中加入 versions 块，列出特性可用的版本简称。例如：

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

其格式与 frontmatter 中的 versions 属性相同。更多信息请参阅 github/docs 仓库 README 中的 Versions。

Liquid 条件语句

现在您可以在内容文件中使用 {% ifversion meow %} ... {% endif %} 了！

Frontmatter

您也可以在内容文件的 frontmatter 中使用该特性。

versions:
  feature: 'meow'

在 versions 下只能出现一个 feature 条目，且 feature 的值只能包含一个特性名称。

您可以在 frontmatter 中同时使用基于特性的版本控制和标准版本控制。这样，文章将在特性文件中指定的所有版本以及 Markdown 文件中直接列出的版本的并集内出现。例如，您可能有一个仅在 GHEC 可用的特性，并已在基于特性的版本文件中声明；但您仍希望该特性的 “About” 文章在 FPT 文档中可见，此时可以在 frontmatter 的 versions 块中同时加入 fpt 与 feature。

versions:
  fpt: '*'
  feature: 'some-new-feature'

最佳实践

版本化内容会影响读者，也会影响所有参与撰写或审阅的人员。以下是一些提升撰写、阅读和审阅体验的建议。并非所有做法都是强制性的，您会遇到边缘情况，但这些启发式原则旨在帮助您更好地思考版本化。

避免不必要的版本化

对读者而言，获取概览性理解往往比阅读精确反映各产品或计划差异的细节更为重要。在概念性或步骤性内容中，尽量以通用方式描述功能或 UI 部分，避免使用版本语法。这样不仅便于我们维护，同时也有助于同时参考多产品文档的读者。

• 请自问：“我能否用一种适用于所有产品且不需版本语法的方式来编写此内容？”
• 如条件允许，请尽量避免为截图进行版本化，因为制作截图的工作量不小。UI 文本的细微差异通常并不影响理解。如果存在针对特定产品的文字或 UI 元素，但截图本身仍能提供有价值的上下文，请思考对截图进行版本化是否会对理解产生实质性影响。
• 如果您能够在不针对特定产品进行版本化的情况下解释概念或引导读者完成流程，请不要对正文进行版本化。

修改已有内容文件时，请频繁且尽早检查现有的版本化

了解已有的版本化能够帮助您编写恰当的版本语句，并提醒您准确地为新内容设定版本。

• 在开始编辑时，请先审阅页面 frontmatter 中的完整版本列表。
• 审阅您正在编辑的内容周围的版本化情况。
• 审阅您所做更改的渲染结果，并在自检时切换至页面的每一种可用版本进行检查。

尽可能避免重复

在同一句或段落中使用版本语法来区分两个计划或产品的正文。贡献者只需在包含版本语句的那段文字上进行编辑，而无需在两个不同的区域分别修改类似但版本不同的正文。审阅者只需提出一次修改建议，而不必在多个位置重复。同样，如果行为差异极大，或在句子/段落内使用版本语法会导致内容难以阅读或理解，则可以考虑在每个相关产品的版本块中重复整段文字，以提升可维护性。

• 请在段落内部直接使用版本语法，以避免重复整句或整段。

  您可以这样写：{% ifversion fpt %}某些内容{% elsif ghec %}其他内容{% endif %}。

• 请自行判断：如果在一句或段落中加入大量版本语法会导致写作或阅读困难，考虑在每个相关产品的版本块中完整重复该段落。

  {% ifversion fpt %}

  如果您使用 Free、Pro 或 Team 计划，您可以执行某些操作。以下是关于 Free、Pro、Team 计划可用功能的更多信息…

  {% elsif ghec %}

  如果您使用 GitHub Enterprise Cloud，您可以执行其他操作。以下是关于 GitHub Enterprise Cloud 可用功能的更多信息…

  {% endif %}

明确而非隐式

如果您清楚内容针对的是哪些产品，请为这些产品显式设定版本。像 not、else 这类语法往往不够精确。not 与 else 的最终效果取决于每篇文章的 frontmatter，导致贡献者需要额外调查才能理解对应的正文，从而增加错误风险。隐式版本化在可复用块（reusables）中尤为复杂，因为引用该可复用块的文章可能拥有不同的版本化，从而对 not 或 else 的求值产生差异。此外，当 GitHub 推出新产品并为 Docs 添加新版本时，原有文章中的 not 与 else 的行为也会随之改变。

• 请记住，GitHub 提供四种产品，且 GitHub Docs 在任意时刻可以展示多达八个版本的文档。
• 在开始编辑时，请审阅整篇文章在 frontmatter 中的版本设置，这有助于您了解 not 与 else 在 Liquid 语句中的行为，或在 frontmatter 中新增版本时可能产生的变化。

在内容设计与创作过程中验证并沟通版本信息

有时某项变更未能赶上其原本计划的发布。通过在内容设计与创作的各个阶段确认版本信息，您可以为审阅者省时，并确保内容在各个发布版本中的准确性。

• 在内容设计阶段请考虑版本化，并在提交给利益相关者审阅时再次核对版本信息。
• 为其他作者和利益相关者减轻审阅负担：在审阅请求中指出不同版本之间的差异，并在必要时链接到具体的渲染版本。
• 信任，但要验证。

测试、测试、再测试

无论是撰写还是审阅内容，请关注内容设计方案及受影响的产品，并在预览或开发环境中检查渲染后的文档，以确保内容对每个产品的描述都是准确的。