forked from github/docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add GitHub AE syntax and additional GitHub Enterprise Server syntax t…
…o internal documentation on Liquid helpers (github#18190)
- Loading branch information
1 parent
7e7268e
commit 0072410
Showing
1 changed file
with
123 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,34 +1,62 @@ | ||
| # 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/docs/liquid)) to create different versions of our content. | ||
|
|
||
| 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 Enterprise <!-- omit in toc --> | ||
| ## Versioning documentation for GitHub.com, GitHub Enterprise Server, and GitHub AE<!-- omit in toc --> | ||
|
|
||
| **In this guide** | ||
| - [Versioned documentation types for GitHub Enterprise](#versioned-documentation-types-for-github-enterprise) | ||
| - [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 GitHub Enterprise](#liquid-conditional-statements-for-github-enterprise) | ||
| - [Including content in *all* supported versions](#including-content-in-all-supported-versions) | ||
| - [Liquid conditional statements for Dotcom](#liquid-conditional-statements-for-dotcom) | ||
| - [Including content that *only applies to Dotcom*](#including-content-that-only-applies-to-dotcom) | ||
| - [Including content for *new Dotcom features* that will be included in Enterprise](#including-content-for-new-dotcom-features-that-will-be-included-in-enterprise) | ||
| - [Including content for *changed* Dotcom features that will also change in Enterprise](#including-content-for-changed-dotcom-features-that-will-also-change-in-enterprise) | ||
| - [Including content for *changed* Dotcom features that will also change in Enterprise but don't exist in some older versions](#including-content-for-changed-dotcom-features-that-will-also-change-in-enterprise-but-dont-exist-in-some-older-versions) | ||
| - [Including content for *new Enterprise features* that don't exist on Dotcom](#including-content-for-new-enterprise-features-that-dont-exist-on-dotcom) | ||
| - [Including content for *changed Enterprise features* that don't exist on Dotcom](#including-content-for-changed-enterprise-features-that-dont-exist-on-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 types for GitHub Enterprise | ||
| ### Versioned documentation | ||
|
|
||
| We provide versioned documentation for GitHub Enterprise users. This means the material on docs.github.com is scoped to specific product offerings. | ||
| 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. | ||
|
|
||
| Documentation for GitHub Enterprise can generally be divided into three types: documentation for the latest release, documentation for any previous supported release, and documentation for a deprecated release. | ||
| #### Dotcom | ||
|
|
||
| Documentation for Dotcom has one version: the latest version. | ||
|
|
||
| #### GitHub Enterprise Server | ||
|
|
||
| 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. | ||
|
|
||
| #### GitHub AE | ||
|
|
||
| Documentation for GitHub AE is similar to Dotcom: we only offer one version of the content for the product, the latest version. | ||
|
|
||
| ### Versioning in the YAML front matter | ||
|
|
||
| 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). | ||
|
|
||
| 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 | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| #### Comparison operators | ||
|
|
||
| |Operator | Meaning| | ||
|
|
@@ -56,34 +84,48 @@ In statements where **at least one** operand must be true for the condition to b | |
|
|
||
| Do **not** use the operators `&&` or `||`. If you do, the content will not render in the intended versions. Only use `and` or `or`. | ||
|
|
||
| ### Liquid conditional statements for GitHub Enterprise | ||
| ### Liquid conditional statements for Dotcom | ||
|
|
||
| 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 currentVersion == "free-pro-team@latest" %}This is how you pay for your personal account, which is something you wouldn't do in Enterprise.{% 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 content. | ||
| 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" | ||
| - `ver_gt` stands for "version greater than" | ||
|
|
||
| See the [Semantic Versioning specification](https://semver.org/#spec-item-11) for more details on version precedence. | ||
|
|
||
| #### Including content in *all* supported versions | ||
| 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. | ||
|
|
||
| If your content is included in all versions of Enterprise, you need not include any Liquid logic at all. The Markdown source will automatically generate the HTML content for all supported versions. | ||
| #### Including content that *only applies to all supported versions of Enterprise Server* | ||
|
|
||
| #### 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 only applies to Enterprise Server, and the content applies to all supported versions, such as subdomain isolation, use this logic: | ||
|
|
||
| ``` | ||
| {% 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 %} | ||
| {% if enterpriseServerVersions contains currentVersion %}Remember to isolate your subdomains, administrator.{% endif %} | ||
| ``` | ||
|
|
||
| In this example: | ||
| - `if currentVersion == "free-pro-team@latest"` will include the content for Dotcom output and *only* Dotcom. | ||
| - `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 | ||
| #### 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, use this logic: | ||
| 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 "[email protected]" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %} | ||
|
|
@@ -92,10 +134,10 @@ If your content is describing a new feature that was added to GitHub.com and wil | |
| In this example: | ||
|
|
||
| - `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output. | ||
| - `or currentVersion ver_gt "[email protected]"` will include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+. | ||
| - `or currentVersion ver_gt "[email protected]"` 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 | ||
| #### 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: | ||
|
|
||
|
|
@@ -106,11 +148,11 @@ If your content is describing a change to existing functionality in Dotcom, such | |
| In this example: | ||
|
|
||
| - `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output. | ||
| - `or currentVersion ver_gt "[email protected]"` will include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+. | ||
| - `or currentVersion ver_gt "[email protected]"` 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 but don't exist in some older versions | ||
| #### 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: | ||
|
|
||
|
|
@@ -129,35 +171,78 @@ This is the old way of doing things (which did not exist before 2.20). | |
| In this example: | ||
|
|
||
| - `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output. | ||
| - `or currentVersion ver_gt "[email protected]"` will include the content for releases *after* Enterprise 2.20, which means the content will be included for 2.21+. | ||
| - `or currentVersion ver_gt "[email protected]"` 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 "[email protected]" and currentVersion ver_lt "[email protected]"` 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 features* that don't exist on Dotcom | ||
| #### 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 but not GitHub, such as LDAP support, use this logic: | ||
| 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 != "free-pro-team@latest" and currentVersion ver_gt "[email protected]" %}This is a brand new feature, admin-type people!{% endif %} | ||
| {% if currentVersion ver_gt "[email protected]" %}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 "[email protected]"` will *additionally* include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+. | ||
| - `and currentVersion ver_gt "[email protected]"` 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 features* that don't exist on Dotcom | ||
| #### 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, such as changed UI text or a more simple means of completing a task in the Management Console, use this logic: | ||
| 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 != "free-pro-team@latest" and currentVersion ver_gt "[email protected]" %}This is the new way of doing things, admins! {% else %}This is the old way of doing things, admins! {% endif %} | ||
| {% if currentVersion ver_gt "[email protected]" %}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 "[email protected]"` will *additionally* include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+. | ||
| - `and currentVersion ver_gt "[email protected]"` 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. | ||
|
|
||
| #### 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. | ||