Versioning documentation

On GitHub Docs, we provide versions of our documentation that reflect the differences in UI and functionality across GitHub's major product offerings. Contributors can use versioning syntax to scope content to a specific product offering.

Versioning syntax allows the reader to manually choose the version of the documentation that applies to the product they're using. GitHub Docs' URLs can also include versioning information, which allows links from one version of GitHub Docs to another to send the reader directly to documentation for the product they're using.

How and where to version

Versioning for content on GitHub Docs is single-source to avoid repetition and keep prose DRY. For articles, you apply versioning to an individual Markdown file with YAML metadata, then use conditional statements within the file's prose to instruct the site which text to display depending on the version the reader selects. Single-sourcing contrasts to the creation of separate files that reflect each version of the content.

There are two types of versioning syntax for GitHub Docs.

YAML: Used most often in YAML front matter within Markdown files in content/, but also in many types of YAML files in data/. Indicates the versioning for an entire piece of content.
```
versions:
  PRODUCT: 'VERSIONS'
  PRODUCT: 'VERSIONS'
  ...
```
The following example shows content versioned for Free, Pro, & Team, and all versions of GitHub Enterprise Server.
```
versions:
  fpt: *
  ghes: *
```
Liquid: Used within Markdown files in content/ and data/reusables/, variable strings within YAML files in data/variables/, or strings within data/glossaries/external.yml. Indicates which text should appear when a reader chooses a version for content that has multiple versions defined by YAML front matter.
- Product-based versioning:
```
{% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
```
- Feature-based versioning:
```
{% ifversion FEATURE-NAME %} ... {% endif %}
```

About the different versions of GitHub

We provide versioned documentation for users of GitHub plans including GitHub Enterprise Cloud and GitHub Enterprise Server. If multiple versions of a page exist on the site, readers can choose the version from the version picker at the top of the page.

GitHub.com

Documentation for GitHub.com has two possible versions:

Free, Pro, or Team plans

For Free, Pro, or Team plans on GitHub.com, use free-pro-team@latest. The short name is fpt.

GitHub Enterprise Cloud

For GitHub Enterprise Cloud, use enterprise-cloud@latest. The short name is ghec.

GitHub Enterprise Server

Documentation for GitHub Enterprise Server has multiple versions and can be divided into two types: documentation for supported releases (we support four at any one time), and documentation for closing down releases (we do not link to these on the Docs site but we support a "frozen" snapshot of these docs in perpetuity, so they can still be accessed if you know the URLs). See lib/enterprise-server-releases.ts for a list.

The versions are named enterprise-server@<release>. The short name is ghes. In Liquid conditionals, we can specify ranges, like ghes > 3.0. For more information, see Versioning with Liquid conditional operators.

Versioning in the YAML frontmatter

You can use the versions property within a file's frontmatter to define which products an article will appear for. Index files require a versions property, but they will be automatically versioned based on the versions of their children.

For example, the following YAML frontmatter will version an article for GitHub Enterprise Server 2.20 and above and Free, Pro, or Team.

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

The following example will version an article for all supported versions of GitHub Enterprise Server:

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

You can also version a page for a range of releases. The following example will version the page for Free, Pro, & Team, GitHub Enterprise Cloud, and GitHub Enterprise Server versions 3.1 and 3.2 only:

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

Versioning with Liquid conditional operators

We use the Liquid template language (specifically, this Node.js port) and a custom {% ifversion ... %} tag to create versions of our documentation.

If you define multiple products in the versions key within a page's YAML frontmatter, you can use the conditional operators ifversion/else (or ifversion/elsif/else) in the Markdown to control how the site renders content on the page for a particular product. For example, a feature may have more options on GitHub.com than on GitHub Enterprise Server, so you can version the content appropriately via the versions frontmatter, and use Liquid conditionals to describe the additional options for GitHub.com.

Note

Use ifversion for product-based versioning and feature-based versioning.
Do not use if or unless.
Make sure to use elsif and not else if. Liquid does not recognize else if and will not render content inside an else if block.

Comparison operators

For versions that don't have numbered releases (like fpt and ghec), you have two options:

{% ifversion ghec %}

Versioning documentation

In this article