版本控制文档

GitHub Docs 使用 YAML 前端内容和 Liquid 运算符，通过单一来源方法支持多个版本的 GitHub。

本文内容

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

版本控制语法允许读者手动选择适用于其所用产品的文档版本。GitHub Docs 的 URL 也包含版本信息，这允许来自 GitHub Docs 一个版本的链接将读者直接定向到其所用产品的文档。

版本控制的方法和位置

GitHub Docs 内容的版本控制采用单一来源方法，以避免重复并保持简洁 DRY。对于文章，您可以使用 YAML 元数据将版本控制应用于单个 Markdown 文件，然后使用文件文本中的条件语句指示站点根据读者选择的版本显示哪些文本。单一来源与创建反映每个内容版本的单独文件形成对比。

GitHub Docs 有两种类型的版本控制语法。

  • YAML：最常用于 `content/` 中 Markdown 文件的 YAML 前端内容，但也用于 `data/` 中许多类型的 YAML 文件。指示整个内容的版本控制。

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

    以下示例显示了为免费版、专业版和团队版以及所有版本的 GitHub Enterprise Server 编制版本的文档。

    versions:
  fpt: *
  ghes: *

  • Liquid：用于 `content/` 和 `data/reusables/` 中的 Markdown 文件，`data/variables/` 中 YAML 文件中的可变字符串，或 `data/glossaries/external.yml` 中的字符串。指示当读者为通过 YAML 前端内容定义了多个版本的文档选择版本时，应显示哪些文本。

    • 基于产品的版本控制

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

    • 基于功能的版本控制

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

关于不同版本的 GitHub

我们为 GitHub 方案的用户（包括 GitHub Enterprise Cloud 和 GitHub Enterprise Server）提供版本控制文档。如果站点上存在页面的多个版本，读者可以从页面顶部的版本选择器中选择版本。

GitHub.com

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

免费版、专业版或团队版

对于 GitHub.com 上的免费版、专业版或团队版，请使用 `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.js 获取列表。

这些版本的名称为 `enterprise-server@`。简写为 `ghes`。在 Liquid 条件语句中，我们可以指定范围，例如 `ghes > 3.0`。有关更多信息，请参阅“使用 Liquid 条件运算符进行版本控制”。

YAML 前端内容中的版本控制

您可以使用文件前端内容中的 `versions` 属性来定义文章将显示在哪些产品中。索引文件需要 `versions` 属性，但它们将根据其子项的版本自动进行版本控制。

例如，以下 YAML 前端内容将为 GitHub Enterprise Server 2.20 及更高版本以及免费版、专业版或团队版编制文章版本。

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

以下示例将为所有受支持版本的 GitHub Enterprise Server 编制页面版本

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

您还可以为一系列版本编制页面版本。以下示例将仅为免费版、专业版和团队版、GitHub Enterprise Cloud 以及 GitHub Enterprise Server 3.1 和 3.2 版本编制页面版本

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

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

我们使用 Liquid 模板语言（特别是 此 Node.js 端口）和自定义的 `{% ifversion ... %}` 标签来创建文档版本。

如果您在页面的 YAML 前端内容中的 `versions` 密钥中定义了多个产品，则可以在 Markdown 中使用条件运算符 `ifversion`/`else`（或 `ifversion`/`elsif`/`else`）来控制站点如何为特定产品呈现页面上的内容。例如，某个功能在 GitHub.com 上可能比在 GitHub Enterprise Server 上具有更多选项，因此您可以通过 `versions` 前端内容适当地编制内容版本，并使用 Liquid 条件语句来描述 GitHub.com 的附加选项。

注意

  • 对于基于产品的版本控制和 基于功能的版本控制，请使用 `ifversion`。
  • 不要使用 `if` 或 `unless`。
  • 确保使用 `elsif` 而非 `else if`。Liquid 无法识别 `else if`，并且不会呈现 `else if` 块内的内容。

比较运算符

对于没有编号版本的版本（如 `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 版本控制包含在它自己的行中，并使用空白控制来去除 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.com（包括 GitHub Enterprise Cloud）流向 GitHub Enterprise Server。

基于功能的版本控制提供了命名的“功能标志”，简化了文档的维护和版本控制。您可以使用单个功能名称（或“标志”）来分组和对整个内容中的散文进行版本控制。当某个功能应用于其他产品时，您只需要更改data/features/中文件的 YAML 版本控制即可。

管理功能

每个功能都通过data/features/中的单个 YAML 文件进行管理。

注意

不要删除data/features/placeholder.yml，因为它被测试使用。

要创建新功能，首先在此目录中使用要使用的功能名称创建一个新的 YAML 文件。对于名为meow的功能，则为data/features/meow.yml。

向 YAML 文件添加一个versions块，其中包含该功能可用的版本的简短名称。例如

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

格式和允许的值与 frontmatter 版本属性相同。有关更多信息，请参阅github/docs存储库自述文件中的“版本”。

Liquid 条件语句

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

前端内容

您也可以在内容文件的 frontmatter 中使用该功能

versions:
  feature: 'meow'

您只能在versions下使用一个feature条目，并且feature的值只能包含一个功能名称。

您可以在 frontmatter 中组合基于功能的版本控制和标准版本控制。当您这样做时，文章将包含在基于功能的版本控制文件和 Markdown 文件中直接指定的版本的所有超集中。例如，您可能有一个目前仅在 GHEC 中可用的功能，这在基于功能的版本控制中指定。但是，您希望此功能的“关于”文章也显示在 FPT 文档中。在这种情况下，您可以将fpt和feature添加到 front matter 中的versions块中

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

最佳实践

版本化内容会影响读者，也会影响任何为内容做出贡献或审查内容的人。以下是一些改进版本控制语法编写、阅读和审查体验的技巧。这些做法都不是强制性的，您会发现一些边缘情况和特殊情况，但它们旨在作为有用的启发式方法来帮助您思考版本控制。

避免不必要的版本控制

对于读者而言，获得一般的理解比阅读精确反映特定产品或计划之间差异的细节更重要。在概念性或程序性内容中，尝试以通用的方式描述功能或 UI 的部分，而无需版本控制语法。这不仅更容易维护，而且还可以增强参考多个产品文档的读者的理解。

  • 请自问：“我能否以适用于所有产品而不使用任何版本控制的方式编写此内容？”
  • 鉴于创建屏幕截图所需的工作量，请尽量避免对屏幕截图进行版本控制。UI 文本之间的细微差异可能不会影响理解。如果存在特定于产品的文本或 UI 元素，但屏幕截图仍然提供有用的上下文，请自问对屏幕截图进行版本控制是否会在有意义的程度上影响理解。
  • 如果您可以解释某个概念或引导读者完成一个过程而无需对特定产品进行版本控制，则不要对散文进行版本控制。

修改现有内容文件时，尽早并经常检查现有版本控制

了解现有的版本控制将有助于确保您编写相关的版本控制语句，并可以提醒您准确地对新内容进行版本控制。

  • 开始编辑时，请检查 front matter 中整个页面的版本控制。
  • 检查您正在编辑的内容周围的版本控制。
  • 检查您正在进行的更改的呈现版本，并在您的自我审查过程中切换到页面的每个可用版本。

尽可能避免重复

在句子或段落中使用版本控制语法来区分针对两个不同计划或产品的散文。贡献者可以只编辑带有版本控制语句的一个段落，而不必考虑更大的版本化文本块并修改两个地方中相似但版本不同的散文。审阅者可以提出一次更改建议，而不必在多个地方留下相同的建议。但是，如果行为差异很大，或者句子或段落中的版本控制变得复杂或难以让贡献者解析，请考虑重复内容以使散文更容易维护。

  • 在段落内内联使用版本控制语法以避免重复句子或整个段落。

    您可以执行 {% ifversion fpt %}某些操作{% elsif ghec %}其他操作{% endif %}。

  • 请运用您的判断：对于在句子或段落中不使用大量版本控制语法就难以编写或阅读的散文，请考虑为每个相关产品在版本块中重复整个段落。

    {% ifversion fpt %}

    如果您使用的是免费、专业版或团队计划，您可以执行某些操作。以下是有关您可以使用免费、专业版或团队计划执行的操作的更多信息……

    {% elsif ghec %}

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

    {% endif %}

明确，而非隐式

如果您确切知道内容描述了哪些产品，请明确地为这些产品进行版本控制。特别是not和else之类的语法可能不够精确。not和else的最终结果取决于每篇文章的前端内容，因此贡献者必须进行更多调查才能理解使用此版本控制的散文。这会造成错误的可能性。隐式版本控制的复杂性在可重用组件中会增加，其中引用可重用组件的文章可能具有不同的版本控制，因此对not或else的评估也不同。当 GitHub 推出新产品时，我们还会偶尔向 GitHub Docs 引入新版本，这会在我们将新版本添加到现有文章时更改not和else的最终结果。

  • 请记住，GitHub 提供四种产品，并且 GitHub Docs 可以在任何给定时间显示多达八个版本的文档。
  • 开始编辑时，请检查整篇文章的前端内容中的版本控制，这可以帮助您了解not和else如何在 Liquid 语句中运行，或者在您启用 front matter 中的新版本时如何更改。

在内容设计和创建过程中验证和沟通版本控制

有时，更改不会包含在其最初预期的版本中。您可以节省审阅者的时间并确保内容更准确，方法是在整个内容设计和创建过程中确认版本控制，包括版本和改进。

  • 请考虑在内容设计中进行版本控制，并在请求利益相关者审查内容创建时仔细检查版本控制。
  • 让其他编写者和利益相关者的审查更容易：在您的审查请求中指出不同版本之间的差异，如有必要，请链接到内容的特定呈现版本。
  • 信任，但要验证。

测试、测试，再测试

无论您是撰写内容还是审核内容，请注意内容设计方案和受影响的产品，并在暂存或开发环境中检查渲染后的内容，以确保内容准确地描述每个产品。