update versions props in yaml too
This commit is contained in:
Sarah Schneider
@@ -1,250 +1,90 @@
|
||||
# Liquid helpers <!-- omit in toc -->
|
||||
|
||||
We use the [Liquid template language](https://shopify.github.io/liquid/basics/introduction/) (specifically, [this Node.js port](https://github.com/docs/liquid)) to create different versions of our content.
|
||||
We use the [Liquid template language](https://shopify.github.io/liquid/basics/introduction/) (specifically, [this Node.js port](https://github.com/harttle/liquidjs)) and a custom `{% ifversion ... %}` tag to create versions of our documentation.
|
||||
|
||||
Note: If you are an open source contributor, you should not worry about versioning content. This document is only here as reference.
|
||||
|
||||
## Versioning documentation for GitHub.com, GitHub Enterprise Server, and GitHub AE<!-- omit in toc -->
|
||||
:arrow_upper_left: TOC
|
||||
|
||||
**In this guide**
|
||||
- [Versioned documentation](#versioned-documentation)
|
||||
- [Dotcom](#dotcom)
|
||||
- [GitHub Enterprise Server](#github-enterprise-server)
|
||||
- [GitHub AE](#github-ae)
|
||||
- [Versioning in the YAML front matter](#versioning-in-the-yaml-front-matter)
|
||||
- [Liquid conditional operators](#liquid-conditional-operators)
|
||||
- [Comparison operators](#comparison-operators)
|
||||
- [Logical operators](#logical-operators)
|
||||
- [Liquid conditional statements for Dotcom](#liquid-conditional-statements-for-dotcom)
|
||||
- [Including content that *only applies to Dotcom*](#including-content-that-only-applies-to-dotcom)
|
||||
- [Liquid conditional statements for GitHub Enterprise Server](#liquid-conditional-statements-for-github-enterprise-server)
|
||||
- [Including content that only applies to all supported versions of Enterprise Server](#including-content-that-only-applies-to-all-supported-versions-of-enterprise-server)
|
||||
- [Including content for *new Dotcom features* that will be included in Enterprise Server](#including-content-for-new-dotcom-features-that-will-be-included-in-enterprise-server)
|
||||
- [Including content for *changed* Dotcom features that will also change in Enterprise Server](#including-content-for-changed-dotcom-features-that-will-also-change-in-enterprise-server)
|
||||
- [Including content for *changed* Dotcom features that will also change in Enterprise Server but don't exist in some older versions](#including-content-for-changed-dotcom-features-that-will-also-change-in-enterprise-server-but-dont-exist-in-some-older-versions)
|
||||
- [Including content for *new Enterprise Server features* that don't exist on Dotcom](#including-content-for-new-enterprise-server-features-that-dont-exist-on-dotcom)
|
||||
- [Including content for *changed Enterprise Server features* that don't exist on Dotcom](#including-content-for-changed-enterprise-server-features-that-dont-exist-on-dotcom)
|
||||
- [Liquid conditional statements for GitHub AE](#liquid-conditional-statements-for-github-ae)
|
||||
- [Including content that *only applies to GitHub AE*](#including-content-that-only-applies-to-github-ae)
|
||||
- [Including content that only applies to *GitHub AE and Enterprise Server*](#including-content-that-only-applies-to-github-ae-and-github-enterprise-server)
|
||||
- [Including content for features that will be included in the *next release* of GitHub AE](#including-content-for-features-that-will-be-included-in-the-next-release-of-github-ae)
|
||||
## Versioned documentation
|
||||
|
||||
### Versioned documentation
|
||||
We provide versioned documentation for users of GitHub.com, Enterprise Server, and GitHub AE (with more to come). If multiple versions of a Docs site page exist, readers can choose the version from the version picker at the top of the page.
|
||||
|
||||
We provide versioned documentation for users of GitHub.com (Dotcom), GitHub Enterprise Server, and GitHub AE. This means the material on docs.github.com is scoped to specific product offerings. If multiple versions of content exist, readers can choose the version from the version picker at the top of the page.
|
||||
### Dotcom
|
||||
|
||||
#### Dotcom
|
||||
Documentation for Dotcom has one version: the `free-pro-team@latest` version. The short name is `fpt`.
|
||||
|
||||
Documentation for Dotcom has one version: the latest version.
|
||||
### Enterprise Server
|
||||
|
||||
#### GitHub Enterprise Server
|
||||
Documentation for 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 **deprecated 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.js` for a list.
|
||||
|
||||
Documentation for GitHub Enterprise Server can generally be divided into three types: documentation for the latest release, documentation for any previous supported release, and documentation for a deprecated release.
|
||||
The versions are named `enterprise-server@<release>`. The short name is `ghes`. In Liquid conditionals, we can specify ranges, like `ghes > 3.0`. (See more on operators below.)
|
||||
|
||||
#### GitHub AE
|
||||
### GitHub AE
|
||||
|
||||
Documentation for GitHub AE is similar to Dotcom: we only offer one version of the content for the product, the latest version.
|
||||
Documentation for GitHub AE is similar to Dotcom: we only offer one version of the content for the product, the `github-ae@latest` version. The short name is `ghae`.
|
||||
|
||||
### Versioning in the YAML front matter
|
||||
## Versioning in the YAML frontmatter
|
||||
|
||||
Use the `versions` key within the file's YAML front matter to define which products an entire page applies to. For more information, see [the _content_ directory's README](/content#versions).
|
||||
Use the `versions` property within the file's frontmatter to define which products an entire page applies to. For more information, see [the _content_ directory's README](/content#versions).
|
||||
|
||||
By default, any text in the body of the Markdown file will display for all product versions that you define in the `versions` key.
|
||||
## Liquid conditional operators
|
||||
|
||||
### Liquid conditional operators
|
||||
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 Dotcom than on GitHub Enterprise Server, so you can version the content for both Dotcom and GitHub Enterprise Server via the `versions` frontmatter, and use Liquid conditionals to describe the additional options for Dotcom.
|
||||
|
||||
If you define multiple products in the `versions` key within a page's YAML front matter, you can use the conditional operators `if`/`else` and `if`/`elsif`/`else` in the page's body to control how the site renders content on the page for a particular product. For example, a feature may have more options on Dotcom than on GitHub Enterprise Server, so you can version the content for both Dotcom and GitHub Enterprise Server via the `versions` front matter, then use Liquid conditionals to describe the additional options for Dotcom within the rendered HTML.
|
||||
Important notes:
|
||||
|
||||
Use the operators in Liquid tags (`{% ... %}`). Do not use `else if`. If you do, the content in that portion of the block will not render.
|
||||
* Make sure to use `ifversion` and not `if`. A test will fail if an `if` statement is used for versioning.
|
||||
* 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
|
||||
### Comparison operators
|
||||
|
||||
|Operator | Meaning|
|
||||
|--|--|
|
||||
|`ver_gt`| Greater than|
|
||||
|`ver_lt`| Less than|
|
||||
|`==`| Equal to|
|
||||
|`!=`| Not equal to**|
|
||||
For versions that don't have numbered releases (like `fpt` and `ghae`), you have two options:
|
||||
|
||||
#### Logical operators
|
||||
* `{% ifversion ghae %}`
|
||||
* `{% ifversion not ghae %}`
|
||||
|
||||
Note: The below examples are only intended to show Liquid syntax and operators. The variables may not reflect what's currently in the content files.
|
||||
For versions that have numbered releases (currently only `ghes`), you can do the same for content that is either available in all of the releases or not available in any of the releases:
|
||||
|
||||
In statements where **all** operands must be true for the condition to be true, use the operator `and`:
|
||||
* `{% ifversion ghes %}`
|
||||
* `{% ifversion not ghes %}`
|
||||
|
||||
If you need to denote content that is only available (or not available) in **certain** releases, you can use the following operators:
|
||||
|
||||
|Operator | Meaning| Example
|
||||
|--|--|--|
|
||||
|`=`| Equal to| `{% ifversion ghes = 3.0 %}`
|
||||
|`>`| Newer than| `{% ifversion ghes > 3.0 %}`
|
||||
|`<`| Older than| `{% ifversion ghes < 3.0 %}`
|
||||
|`!=`| Not equal to| `{% ifversion ghes != 3.0 %}` (don't use `not` in ranges)
|
||||
|
||||
### Logical operators
|
||||
|
||||
When **all** operands must be true for the condition to be true, use the operator `and`:
|
||||
|
||||
```
|
||||
{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %}
|
||||
{% ifversion fpt and ghes > 2.21 %}
|
||||
```
|
||||
|
||||
In statements where **at least one** operand must be true for the condition to be true, use the operator `or`:
|
||||
When **at least one** operand must be true for the condition to be true, use the operator `or`:
|
||||
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
|
||||
{% ifversion fpt or ghes > 2.21 %}
|
||||
```
|
||||
|
||||
Do **not** use the operators `&&` or `||`. If you do, the content will not render in the intended versions. Only use `and` or `or`.
|
||||
Do **not** use the operators `&&` or `||`. Liquid does not recognize them, and the content will not render in the intended versions.
|
||||
|
||||
### Liquid conditional statements for Dotcom
|
||||
### Versioning content for _future_ releases of GitHub AE
|
||||
|
||||
If the Markdown source's `versions` front matter includes Dotcom and you want the content to display for Dotcom, do not include any Liquid logic at all. Deploying the site will automatically generate the HTML content for Dotcom.
|
||||
|
||||
#### Including content that *only applies to Dotcom*
|
||||
|
||||
If your content only applies to GitHub.com, such as billing information, use this logic:
|
||||
If your content describes a feature that will be included in the next release of GitHub AE, you can use a placeholder version string, `ghae-next`. Before the next GitHub AE release, we will run a script to replace the placeholder with `ghae`.
|
||||
|
||||
For example, you can use this logic before the feature is available in GitHub AE:
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" %}This is how you pay for your personal account, which is something you wouldn't do in Enterprise.{% endif %}
|
||||
{% ifversion fpt or ghae-next %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
|
||||
```
|
||||
After the feature becomes available in GitHub AE and we run the replacement script, this statement will become:
|
||||
```
|
||||
{% ifversion fpt or ghae %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `if currentVersion == "free-pro-team@latest"` will include the content for Dotcom output and *only* Dotcom.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
### Liquid conditional statements for GitHub Enterprise Server
|
||||
|
||||
Use the custom `ver_gt` and `ver_lt` Liquid operators to conditionally include or exclude GitHub Enterprise Server content.
|
||||
|
||||
- `ver_lt` stands for "version less than"
|
||||
- `ver_gt` stands for "version greater than"
|
||||
|
||||
See the [Semantic Versioning specification](https://semver.org/#spec-item-11) for more details on version precedence.
|
||||
|
||||
If the Markdown source's `versions` front matter includes a version or versions of GitHub Enterprise Server and you want the content to display for those versions of GitHub Enterprise Server, do not include any Liquid logic at all. Deploying the site will automatically generate the HTML content for the supported versions of GitHub Enterprise Server.
|
||||
|
||||
#### Including content that *only applies to all supported versions of Enterprise Server*
|
||||
|
||||
If your content only applies to Enterprise Server, and the content applies to all supported versions, such as subdomain isolation, use this logic:
|
||||
|
||||
```
|
||||
{% if enterpriseServerVersions contains currentVersion %}Remember to isolate your subdomains, administrator.{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `if enterpriseServerVersions contains currentVersion` checks to see if the version of the article you're viewing, `currentVersion`, is a supported version of Enterprise Server within an array of the supported versions of Enterprise Server, `enterpriseServerVersions`.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for *new Dotcom features* that will be included in Enterprise Server
|
||||
|
||||
If your content is describing a new feature that was added to GitHub.com and will be automatically included in the next release of GitHub Enterprise Server, use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
|
||||
- `or currentVersion ver_gt "enterprise-server@2.21"` will include the content for releases *after* Enterprise Server 2.21, which means the content will be included for 2.22+.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for *changed* Dotcom features that will also change in Enterprise Server
|
||||
|
||||
If your content is describing a change to existing functionality in Dotcom, such as changed UI text or a more simple means of completing a task, use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" %}This is the new way of doing things {% else %}This is the old way of doing things {% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
|
||||
- `or currentVersion ver_gt "enterprise-server@2.21"` will include the content for releases *after* Enterprise Server 2.21, which means the content will be included for 2.22+.
|
||||
- `{% else %}` means if the above is NOT true, then display the content that follows, `This is the old way of doing things`.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for *changed* Dotcom features that will also change in Enterprise Server but don't exist in some older versions
|
||||
|
||||
If your content is describing a change to existing functionality in Dotcom, and that functionality doesn't exist in all older Enterprise versions, use logic like this:
|
||||
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" %}
|
||||
|
||||
This is the new way of doing things.
|
||||
|
||||
{% elsif currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "enterprise-server@2.21" %}
|
||||
|
||||
This is the old way of doing things (which did not exist before 2.20).
|
||||
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
|
||||
- `or currentVersion ver_gt "enterprise-server@2.20"` will include the content for releases *after* Enterprise Server 2.20, which means the content will be included for 2.21+.
|
||||
- `elsif currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "enterprise-server@2.21"` means if the above is NOT true, and the version is 2.20, then display the content that follows, `This is the old way of doing things`. No content will be displayed for versions older than 2.20.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for *new Enterprise Server features* that don't exist on Dotcom
|
||||
|
||||
If your content is describing a new feature that was added to GitHub Enterprise Server but not GitHub, such as LDAP support, use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion ver_gt "enterprise-server@2.21" %}This is a brand new feature, admin-type people!{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion != "free-pro-team@latest"` will exclude the content for GitHub.com output.
|
||||
- `and currentVersion ver_gt "enterprise-server@2.21"` will *additionally* include the content for releases *after* Enterprise Server 2.21, which means the content will be included for 2.22+.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for *changed Enterprise Server features* that don't exist on Dotcom
|
||||
|
||||
If your content is describing a change to existing functionality in GitHub Enterprise Server, such as changed UI text or a more simple means of completing a task in the Management Console, use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion ver_gt "enterprise-server@2.21" %}This is the new way of doing things, admins! {% else %}This is the old way of doing things, admins! {% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion != "free-pro-team@latest"` will exclude the content for GitHub.com output.
|
||||
- `and currentVersion ver_gt "enterprise-server@2.21"` will *additionally* include the content for releases *after* Enterprise Server 2.21, which means the content will be included for 2.22+.
|
||||
- `{% else %}` means if the above is NOT true, then display the content that follows, `This is the old way of doing things, admins!`.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
### Liquid conditional statements for GitHub AE
|
||||
|
||||
If the Markdown source's `versions` front matter includes GitHub AE and you want the content to display for GitHub AE, do not include any Liquid logic at all. Deployment of the site will automatically generate the HTML content for GitHub AE.
|
||||
|
||||
You may notice version strings like <code>issue-<em>####</em></code> for content versioned for GitHub AE. The content with this versioning will not render on GitHub Docs, and these strings are internal references. These strings are only intended to be edited by GitHub staff.
|
||||
|
||||
#### Including content that *only applies to GitHub AE*
|
||||
|
||||
If your content only applies to GitHub AE, use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion == "github-ae@latest" %}This content describes something you can only do on GitHub AE.{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `if currentVersion == "github-ae@latest"` will include the content for GitHub AE output and *only* GitHub AE.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content that *only applies to GitHub AE and Enterprise Server*
|
||||
|
||||
If your content only applies to GitHub AE and all supported versions of GitHub Enterprise Server, use this logic:
|
||||
|
||||
```
|
||||
{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}This content describes something you can only do on GitHub Enterprise Server or GitHub AE.{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `if enterpriseServerVersions contains currentVersion` will include the content for all supported versions of GitHub Enterprise Server.
|
||||
- `or currentVersion == "github-ae@latest"` will include the content for GitHub AE output.
|
||||
- `{% endif %}` ends the statement.
|
||||
|
||||
#### Including content for features that will be included in the *next release* of GitHub AE
|
||||
|
||||
If your content is describing a feature that will be included in the next release of GitHub AE, you can use a placeholder version string, `github-ae@next`. Before the next GitHub AE release, replace the instances of the placeholder with `github-ae@latest`. For example, you can use this logic:
|
||||
|
||||
```
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@next" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
|
||||
- `or currentVersion == "github-ae@next"` indicates that the content should also appear for the next release of GitHub AE, when we replace any instances of `github-ae@next` with `github-ae@latest`.
|
||||
- `{% endif %}` ends the statement.
|
||||
`ifversion` tags can also support `ghae-issue-<number>` as an additional way to version content more granularly for upcoming GitHub AE releases.
|
||||
|
||||
Reference in New Issue
Block a user