Create function to allow a reusable to link current article in a diff…

…erent docs version (github#34273) Co-authored-by: Peter Bengtsson <peterbe@github.com>
drakogang · Feb 2, 2023 · 03a971c · 03a971c
1 parent d09e48e
commit 03a971c
Show file tree

Hide file tree

Showing 18 changed files with 65 additions and 77 deletions.
diff --git a/content/README.md b/content/README.md
@@ -35,9 +35,12 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
 - [Versioning](#versioning)
 - [Filenames](#filenames)
 - [Whitespace control](#whitespace-control)
-- [Links and image paths](#links-and-image-paths)
+- [Links](#links)
+  - [Linking to the current article in a different version of the docs](#linking-to-the-current-article-in-a-different-version-of-the-docs)
   - [Preventing transformations](#preventing-transformations)
+  - [Legacy filepaths and redirects for links](#legacy-filepaths-and-redirects-for-links)
   - [Index pages](#index-pages)
+  - [Home page](#homepage)
   - [Creating new product guides pages](#creating-new-product-guides-pages)
 
 ## Frontmatter
@@ -355,6 +358,19 @@ and when viewed on GitHub Enterprise Server docs, the version is included as wel
 /en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply
 ```
 
+### Linking to the current article in a different version of the docs
+
+Sometimes you may want to link from an article to the same article in a different product version. For example:
+
+- You mention some functionality that is not available for free, pro, or team plans and you want to link to the GitHub Enterprise Cloud version of the same page.
+- The GitHub Enterprise Server version of an article describes a feature that shipped with that version, but site administrators can upgrade to the latest version of the feature that's in use on GitHub Enterprise Cloud.
+
+You can link directly to a different version of the page using the `currentArticle` property. This means that the link will continue to work directly even if the article URL changes.
+
+```markdown
+{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).{% endif %}
+```
+
 ### Preventing transformations
 
 Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, you should include the preferred version in the path.

diff --git a/...de-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository.md b/...de-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository.md
@@ -39,13 +39,7 @@ You decide how to generate {% data variables.product.prodname_code_scanning %} a
 {% data reusables.code-scanning.about-analysis-origins-link %}
 {% endif %}
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** If you want to use the {% data variables.product.prodname_codeql %} analysis, note that this article describes the features available with the version of the {% data variables.product.prodname_codeql %} action and associated {% data variables.product.prodname_codeql_cli %} bundle included in the initial release of this version of {% data variables.product.product_name %}. If your enterprise uses a more recent version of the {% data variables.product.prodname_codeql %} action, see the [{% data variables.product.prodname_ghe_cloud %} article](/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository) for information on the latest features. {% ifversion not ghae %} For information on using the latest version, see "[Configuring code scanning for your appliance](/admin/advanced-security/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)."{% endif %}
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-action-version-ghes %}
 
 {% ifversion ghae %}
 ## Prerequisites
@@ -96,14 +90,6 @@ The advanced setup for {% data variables.product.prodname_code_scanning %} is he
 
 {% data reusables.advanced-security.starter-workflows-beta %}
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** This article describes the features available with the version of the {% data variables.product.prodname_codeql %} action and associated {% data variables.product.prodname_codeql_cli %} bundle included in the initial release of this version of {% data variables.product.product_name %}. If your enterprise uses a more recent version of the {% data variables.product.prodname_codeql %} action, see the [{% data variables.product.prodname_ghe_cloud %} article](/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository) for information on the latest features. {% ifversion not ghae %} For information on using the latest version, see "[Configuring code scanning for your appliance](/admin/advanced-security/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)."{% endif %}
-
-{% endnote %}
-{% endif %}
-
 {% data reusables.advanced-security.starter-workflow-overview %} {% data variables.product.prodname_code_scanning_capc %} starter workflows are only available for your repository if {% data variables.product.prodname_code_scanning %} is enabled.
 
 {% data reusables.code-scanning.billing %}

diff --git a/...-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md b/...-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md
@@ -30,13 +30,7 @@ shortTitle: Customize code scanning
 {% data reusables.code-scanning.beta %}
 {% data reusables.code-scanning.enterprise-enable-code-scanning-actions %}
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** This article describes the features available with the version of the CodeQL action and associated CodeQL CLI bundle included in the initial release of this version of {% data variables.product.product_name %}. If your enterprise uses a more recent version of the CodeQL action, see the [{% data variables.product.prodname_ghe_cloud %} article](/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning) for information on the latest features. {% ifversion not ghae %} For information on using the latest version, see "[Configuring {% data variables.product.prodname_code_scanning %} for your appliance](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)."{% endif %}
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-action-version-ghes %}
 
 ## About {% data variables.product.prodname_code_scanning %} configuration
 

diff --git a/...e-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container.md b/...e-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container.md
@@ -48,13 +48,7 @@ You may have difficulty running {% data variables.product.prodname_code_scanning
 
 ## Example workflow
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** This article describes the features available with the version of the CodeQL action and associated CodeQL CLI bundle included in the initial release of this version of {% data variables.product.product_name %}. If your enterprise uses a more recent version of the CodeQL action, see the [{% data variables.product.prodname_ghe_cloud %} article](/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container) for information on the latest features.{% ifversion not ghae %} For information on using the latest version, see "[Configuring code scanning for your appliance](/admin/advanced-security/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)."{% endif %}
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-action-version-ghes %}
 
 This sample workflow uses {% data variables.product.prodname_actions %} to run {% data variables.product.prodname_codeql %} analysis in a containerized environment. The value of `container.image` identifies the container to use. In this example the image is named `codeql-container`, with a tag of `f0f91db`. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idcontainer)."
 

diff --git a/...your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md b/...your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md
@@ -34,13 +34,7 @@ allowTitleToDifferFromFilename: true
 {% data reusables.code-scanning.beta %}
 {% data reusables.code-scanning.not-available %}
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** This article describes the features available with the version of the {% data variables.product.prodname_codeql %} action and associated {% data variables.product.prodname_codeql_cli %} bundle included in the initial release of this version of {% data variables.product.product_name %}. If your enterprise uses a more recent version of the {% data variables.product.prodname_codeql %} action, see the [{% data variables.product.prodname_ghe_cloud %} article](/enterprise-cloud@latest/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-your-advanced-setup-for-codeql) for information on the latest features. {% ifversion not ghae %} For information on using the latest version, see "[Configuring {% data variables.product.prodname_code_scanning %} for your appliance](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)."{% endif %}
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-action-version-ghes %}
 
 ## Producing detailed logs for debugging
 

diff --git a/...anning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md b/...anning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md
@@ -24,13 +24,7 @@ topics:
 ---
 {% data reusables.code-scanning.enterprise-enable-code-scanning %}
 
-{% ifversion ghes or ghae %}
-{% note %}
-
-**Note:** This article describes features present in the version of {% data variables.product.prodname_codeql_cli %} available at the time of the release of {% data variables.product.product_name %}. If your enterprise uses a more recent version of {% data variables.product.prodname_codeql_cli %}, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system) instead.
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
 
 ## About generating code scanning results with {% data variables.product.prodname_codeql_cli %}
 

diff --git a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs.md b/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs.md
@@ -16,13 +16,7 @@ topics:
 
 ## About {% data variables.product.prodname_codeql %} packs
 
-{% ifversion ghes %}
-{% note %}
-
-**Note:** If you have manually updated your {% data variables.product.prodname_codeql_cli %} version to a newer version than what is covered in this article, please see “[About {% data variables.product.prodname_codeql %} packs](/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)”, the Enterprise Cloud version, for the most up-to-date documentation.
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
 
 {% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. You can publish your own {% data variables.product.prodname_codeql %} packs and download packs created by others. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata.
 

diff --git a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces.md b/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces.md
@@ -14,13 +14,7 @@ topics:
 
 ## About {% data variables.product.prodname_codeql %} workspaces
 
-{% ifversion ghes %}
-{% note %}
-
-**Note:** If you have manually updated your {% data variables.product.prodname_codeql_cli %} version to a newer version than what is covered in this article, please see “[About {% data variables.product.prodname_codeql %} workspaces](/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces)”, the Enterprise Cloud version, for the most up-to-date documentation.
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-action-version-ghes %}
 
 You use a {% data variables.product.prodname_codeql %} workspace when you want to group multiple {% data variables.product.prodname_codeql %} packs together. A typical use case for a {% data variables.product.prodname_codeql %} workspace is to develop a set of {% data variables.product.prodname_codeql %} library and query packs that are mutually dependent. For more information on {% data variables.product.prodname_codeql %} packs, see “[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs).”
 

diff --git a/...rity/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md b/...rity/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md
@@ -18,6 +18,8 @@ topics:
 
 ## About analyzing databases with the {% data variables.product.prodname_codeql_cli %}
 
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
+
 To analyze a codebase, you run queries against a CodeQL
 database extracted from the code.
 

diff --git a/...urity/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs.md b/...urity/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs.md
@@ -16,13 +16,7 @@ topics:
 
 ## About {% data variables.product.prodname_codeql %} packs and the {% data variables.product.prodname_codeql_cli %}
 
-{% ifversion ghes %}
-{% note %}
-
-**Note:** If you have manually updated your {% data variables.product.prodname_codeql_cli %} version to a newer version than what is covered in this article, please see “[Creating and working with {% data variables.product.prodname_codeql %} packs](/enterprise-cloud@latest/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs)”, the Enterprise Cloud version, for the most up-to-date documentation.
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
 
 With {% data variables.product.prodname_codeql %} packs and the package management commands in the {% data variables.product.prodname_codeql_cli %}, you can publish your custom queries and integrate them into your codebase analysis.
 

diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases.md b/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases.md
@@ -17,6 +17,8 @@ topics:
 
 ## About creating {% data variables.product.prodname_codeql %} databases
 
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
+
 Before you analyze your code using {% data variables.product.prodname_codeql %}, you need to create a {% data variables.product.prodname_codeql %} database containing all the data required to run queries on your code. You can create {% data variables.product.prodname_codeql %} databases yourself using the {% data variables.product.prodname_codeql_cli %}, or download them from {% data variables.product.prodname_dotcom_the_website %}.
 
 {% data variables.product.prodname_codeql %} analysis relies on extracting relational data from your code, and using it to build a [{% data variables.product.prodname_codeql %} database](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database). {% data variables.product.prodname_codeql %} databases contain all of the important information about a codebase, which can be analyzed by executing {% data variables.product.prodname_codeql %} queries against it. {% data variables.product.prodname_dotcom %} creates and stores {% data variables.product.prodname_codeql %} databases for a large number of open-source projects. For more information, see “[Downloading {% data variables.product.prodname_codeql %} databases from {% data variables.product.prodname_dotcom_the_website %}](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases#downloading-databases-from-githubcom).”

diff --git a/...t/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.md b/...t/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.md
@@ -17,6 +17,8 @@ topics:
 
 ## About creating {% data variables.product.prodname_codeql %} query suites
 
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
+
 {% data variables.product.prodname_codeql %} query suites provide a way of selecting queries, based on their
 filename, location on disk{% ifversion codeql-packs %} or in a {% data variables.product.prodname_codeql %} pack{% endif %}, or metadata properties.
 Create query suites for the queries that you want to frequently use in

diff --git a/...security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.md b/...security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.md
@@ -18,6 +18,8 @@ topics:
 
 ## Getting started with the {% data variables.product.prodname_codeql_cli %}
 
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
+
 To run {% data variables.product.prodname_codeql %} commands, you need to set up the CLI so that it can access
 the tools, queries, and libraries required to create and analyze databases.
 

diff --git a/...e-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs.md b/...e-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs.md
@@ -16,13 +16,7 @@ topics:
 
 ## Configuring the `qlpack.yml` file before publishing
 
-{% ifversion ghes %}
-{% note %}
-
-**Note:** If you have manually updated your {% data variables.product.prodname_codeql_cli %} version to a newer version than what is covered in this article, please see “[Publishing and using {% data variables.product.prodname_codeql %} packs](/enterprise-cloud@latest/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)”, the Enterprise Cloud version, for the most up-to-date documentation.
-
-{% endnote %}
-{% endif %}
+{% data reusables.code-scanning.codeql-cli-version-ghes %}
 
 You can check and modify the configuration details of your {% data variables.product.prodname_codeql %} pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor.
 

diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md
@@ -4,7 +4,7 @@ Welcome to the content style guide for [GitHub Docs](https://docs.github.com/).
 
 These guidelines are specific to GitHub’s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see our [markup reference guide](content-markup-reference.md). For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)"
 
-Use table of contents icon <img src="../assets/images/table-of-contents.png" width="25" height="25" /> on the top left corner of this document to get to a specific section of this guide quickly.
+Use table of contents icon <img src="../assets/images/table-of-contents.png" width="25" height="25" /> on the top right corner of this document to get to a specific section of this guide quickly.
 
 ## The GitHub Docs approach to style
 
@@ -342,21 +342,23 @@ For more information on links and accessibility, see “[Links](https://readabil
 
 ### Links between versions
 
-Sometimes, you need to link from one version of GitHub Docs to another. For example, the Free, Pro, & Team version of "[Managing the publication of GitHub Pages sites for your organization](https://docs.github.com/en/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)" might link to the Enterprise Cloud version of the same article like this:
+Sometimes, you need to link from one version of GitHub Docs to another. When you want to link to a different version of the _same_ page, you should use the `currentArticle` property.
+
+For example, the Free, Pro, & Team version of "[Managing the publication of GitHub Pages sites for your organization](https://docs.github.com/en/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)" might link to the Enterprise Cloud version of the same article like this:
 
 >You can choose to allow or disallow the publication of GitHub Pages sites.
 >
->Organizations that use GitHub Enterprise Cloud can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the GitHub Enterprise Cloud documentation](/enterprise-cloud@latest/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization).
+>Organizations that use GitHub Enterprise Cloud can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the GitHub Enterprise Cloud documentation](/enterprise-cloud@latest/{{ currentArticle }}).
 
 To link to a different article in a different version, use this format:
 
 > For more information, see "[ARTICLE TITLE]()" in the VERSION documentation.
 
 To link to the same article in a different version, use this format:
 
-> For more information, see [the VERSION documentation]().
+> For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).
 
-To link to a specific version, you must include the version in the path (e.g., `/enterprise-cloud@latest/admin/overview/about-enterprise-accounts`).
+To link to a specific version, you must include the version in the path (e.g., `/enterprise-cloud@latest/{{ currentArticle }}`).
 
 ### Links to specific sections of articles