Create function to allow a reusable to link current article in a different docs version (#34273)
Co-authored-by: Peter Bengtsson <peterbe@github.com>
This commit is contained in:
Felicity Chapman
@@ -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.
|
||||
|
||||
@@ -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 %}
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)."
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 %}
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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).”
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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).”
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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,11 +342,13 @@ 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:
|
||||
|
||||
@@ -354,9 +356,9 @@ To link to a different article in a different version, use this format:
|
||||
|
||||
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
|
||||
|
||||
|
||||
10
data/reusables/code-scanning/codeql-action-version-ghes.md
Normal file
10
data/reusables/code-scanning/codeql-action-version-ghes.md
Normal file
@@ -0,0 +1,10 @@
|
||||
{% 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 %} version](/enterprise-cloud@latest/{{ currentArticle }}) of this article 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 %}
|
||||
9
data/reusables/code-scanning/codeql-cli-version-ghes.md
Normal file
9
data/reusables/code-scanning/codeql-cli-version-ghes.md
Normal file
@@ -0,0 +1,9 @@
|
||||
{% ifversion ghes %}
|
||||
{% note %}
|
||||
|
||||
**Note:** This article describes the features available with the {% data variables.product.prodname_codeql_cli %} {% data variables.product.codeql_cli_ghes_recommended_version %} bundle included in the initial release of {% data variables.product.product_name %} {{ allVersions[currentVersion].currentRelease }}.
|
||||
|
||||
If your site administrator has updated your {% data variables.product.prodname_codeql_cli %} version to a newer release, please see the [{% data variables.product.prodname_ghe_cloud %} version](/enterprise-cloud@latest/{{ currentArticle }}) of this article for information on the latest features.
|
||||
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
@@ -17,6 +17,7 @@ const {
|
||||
getProductStringFromPath,
|
||||
getCategoryStringFromPath,
|
||||
getPathWithoutLanguage,
|
||||
getPathWithoutVersion,
|
||||
} = pathUtils
|
||||
|
||||
// This doesn't change just because the request changes, so compute it once.
|
||||
@@ -44,6 +45,10 @@ export default async function contextualize(req, res, next) {
|
||||
req.context.activeProducts = activeProducts
|
||||
req.context.allVersions = allVersions
|
||||
req.context.currentPathWithoutLanguage = getPathWithoutLanguage(req.pagePath)
|
||||
|
||||
// define property for writers to link to the current page in a different version
|
||||
// includes any type of rendered page not just "articles"
|
||||
req.context.currentArticle = getPathWithoutVersion(req.context.currentPathWithoutLanguage)
|
||||
req.context.currentPath = req.pagePath
|
||||
req.context.query = req.query
|
||||
req.context.languages = languages
|
||||
|
||||
Reference in New Issue
Block a user