diff --git a/content/README.md b/content/README.md index 08eed6cc1510..a493d1e2b082 100644 --- a/content/README.md +++ b/content/README.md @@ -2,12 +2,12 @@ The `/content` directory is where all the site's (English) Markdown content lives! -See the [markup reference guide](contribution/content-markup-reference.md) for more information about supported Markdown features. +See the [markup reference guide](contributing/content-markup-reference.md) for more information about supported Markdown features. -See the repository's top-level [README](../README.md) for general information about how the site works. +See the [contributing docs](contributing) for general information about working with the docs. - [Frontmatter](#frontmatter) - - [`productVersions`](#productversions) + - [`versions`](#versions) - [`redirect_from`](#redirect_from) - [`title`](#title) - [`shortTitle`](#shorttitle) @@ -38,48 +38,39 @@ The following frontmatter values have special meanings and requirements for this There's also a schema that's used by the test suite to validate every page's frontmatter. See [`lib/frontmatter.js`](../lib/frontmatter.js). -### `productVersions` +### `versions` -- Purpose: Indicates the products and product versions to which a page applies. +- Purpose: Indicates the [versions](../lib/all-versions.js) to which a page applies. See [Versioning](#versioning) for more info. -- Type: `Object`. Allowable keys map to product names and can be found in the `productVersions` object in [`lib/frontmatter.js`](../lib/frontmatter.js). +- Type: `Object`. Allowable keys map to product names and can be found in the `versions` object in [`lib/frontmatter.js`](../lib/frontmatter.js). - This frontmatter value is currently **required** for all pages. +- The `*` is used to denote all releases for the version. -Example that applies to GitHub.com and recent versions of GitHub Enterprise: +Example that applies to GitHub.com and recent versions of GitHub Enterprise Server: ```yml title: About your personal dashboard -productVersions: - dotcom: '*' - enterprise: '>=2.14' +versions: + free-pro-team: '*' + enterprise-server: '>=2.20' ``` -Example that applies to all supported versions of GitHub enterprise +Example that applies to all supported versions of GitHub Enterprise Server: (but not GitHub.com): ```yml title: Downloading your license -productVersions: - enterprise: '*' +versions: + enterprise-server: '*' ``` -Example that applies to GitHub Actions: - -```yml -title: Building actions -productVersions: - actions: '*' -``` - -Note: Every product except `enterprise` is an evergreen product without specific versions, so the `*` is used to denote all versions. - ### `redirect_from` - Purpose: List URLs that should redirect to this page. -- Type: `Array` (for multiple redirects) or `String` (for just one) +- Type: `Array` - Optional -Example with multiple redirects: +Example: ```yml title: Getting started with GitHub Desktop @@ -89,14 +80,7 @@ redirect_from: - /articles/getting-started-with-github-for-windows/ ``` -Example with a single redirect: - -```yml -title: Denying access to a previously approved OAuth App for your organization -redirect_from: /articles/denying-access-to-a-previously-approved-application-for-your-organization/ -``` - -See [README#redirects](../README.md#redirects) for more info. +See [`contributing/redirects`](contributing/redirects.md) for more info. ### `title` @@ -108,7 +92,7 @@ See [README#redirects](../README.md#redirects) for more info. - Purpose: An abbreviated variant of the page title for use in breadcrumbs. - Type: `String` -- Optional. If omitted, `title` will be used. Used only for map topic and category pages. +- Optional. If omitted, `title` will be used. Example: @@ -163,7 +147,7 @@ For a layout named `layouts/article.html`, the value would be `article`. ### `miniTocMaxHeadingLevel` - Purpose: Indicates the maximum heading level to include in an article's mini TOC. See [Autogenerated mini TOCs](#autogenerated-mini-tocs) for more info. -- Type: `Number`. Default is `3`. Minimum is `2`. Maximum is `4` for now. (If we need to add more levels, we can revisit this. We will need to add CSS to do deeper nesting.) +- Type: `Number`. Default is `3`. Minimum is `2`. Maximum is `4`. - Optional. ### `allowTitleToDifferFromFilename` @@ -193,56 +177,16 @@ Make sure not to add hardcoded "In this article" sections in the Markdown source ## Versioning -Versioning for any content file lives in **two** places: - -* The file's [`productVersions`](#productversions) frontmatter. -* Liquid conditionals in the file's parent [index page](#index-pages). - -For example, an article with this frontmatter: - -```yml -title: About your personal dashboard -productVersions: - dotcom: '*' - enterprise: '>=2.14' -``` - -should be referenced in the parent index page like this: +A content file can have **two** types of versioning: -``` -{%- if page.version == 'dotcom' or page.version ver_gt "2.13" %} -- About your personal dashboard -{%- endif %} -``` +* [`versions`](#versions) frontmatter (**required**) + * Determines in which the versions the page is available. See [contributing/permalinks](../contributing/permalinks.md) for more info. +* Liquid statements in content (**optional**) + * Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files. ## Filenames -The site automatically creates links to articles in index pages. For example, this block in `content/index.md`: - -``` -## Bootcamp - -- Set up git -- Create a repo -- Fork a repo -- Be social -``` - -renders with links to each article. - -If you're adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in both the article and the parent index. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). If you're not sure what the filename should be based on the title, you can find out by adding the title to the TOC. For example: - -``` -## Bootcamp - -- Set up git -- Create a repo -- Fork a repo -- Be social -- I'm a new article -``` - -Then just run the site locally and see what the link is. In this example, the filename would be: `im-a-new-article` +When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter. ## Whitespace control @@ -258,31 +202,31 @@ These characters are especially important in [index pages](#index-pages) compris ## Links and image paths -Any local links (like those starting with `/articles/`) and image paths (starting with `/assets`) that you include in content and data files will undergo some transformations on the server side to match the current page's language and Enterprise version (if applicable). The handling for these transformations lives in [`lib/rewrite-local-links`](lib/rewrite-local-links.js) and [`lib/rewrite-asset-paths-to-s3`](lib/rewrite-asset-paths-to-s3.js). +Local links must start with a product ID (like `/actions` or `/admin`), and image paths must start with `/assets`. These links undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/rewrite-local-links`](lib/rewrite-local-links.js) and [`lib/rewrite-asset-paths-to-s3`](lib/rewrite-asset-paths-to-s3.js). For example, if you include the following link in a content file: ``` -/articles/creating-a-saved-reply +/github/writing-on-github/creating-a-saved-reply ``` -When viewed on Dotcom, the link gets rendered with the language code: +When viewed on GitHub.com docs, the link gets rendered with the language code and version: ``` -/en/articles/creating-a-saved-reply +/en/free-pro-team@latest/github/writing-on-github/creating-a-saved-reply ``` -and when viewed on GHE, the version is included as well: +and when viewed on GitHub Enterprise Server docs, the version is included as well: ``` -/en/enterprise/2.16/user/articles/creating-a-saved-reply +/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply ``` -The transformation is a little simpler for image paths. If you include the following image path in a content file: +The transformation is a little different for image paths. If you include the following image path in a content file: ``` /assets/images/help/profile/follow-user-button.png ``` -when viewed on GHE, the path gets rewritten to include S3: +when viewed on GitHub Enterprise Server docs, the path gets rewritten to include S3: ``` -https://github-images.s3.amazonaws.com/enterprise/2.16/assets/images/help/profile/follow-user-button.png +https://github-images.s3.amazonaws.com/enterprise/2.20/assets/images/help/profile/follow-user-button.png ``` ### Preventing transformations @@ -290,7 +234,7 @@ https://github-images.s3.amazonaws.com/enterprise/2.16/assets/images/help/profil 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, write the link using HTML and add a class of `dotcom-only`. For example: ``` -GitHub's Terms of Service +GitHub's Terms of Service ``` -Sometimes the canonical home of content moves outside the help site. None of the links included in [`lib/external-redirects.json`](lib/external-redirects.json) get rewritten. See the top-level [README](../README.md#external-redirects) for more info about this type of redirect. \ No newline at end of file +Sometimes the canonical home of content moves outside the docs site. None of the links included in [`lib/redirects/external-redirects.json`](lib/redirects/external-redirects.json) get rewritten. See [`contributing/redirects.md`](contributing/redirects.md) for more info about this type of redirect. diff --git a/contributing/liquid-helpers.md b/contributing/liquid-helpers.md index 404f7593d54a..df19388b064e 100644 --- a/contributing/liquid-helpers.md +++ b/contributing/liquid-helpers.md @@ -45,13 +45,13 @@ Note: The below examples are only intended to show Liquid syntax and operators. In statements where **all** operands must be true for the condition to be true, use the operator `and`: ``` -{% if page.version != "dotcom" and page.version ver_gt "2.6" %} +{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %} ``` In statements where **at least one** operand must be true for the condition to be true, use the operator `or`: ``` -{% if page.version == "dotcom" or page.version ver_gt "2.6" %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@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`. @@ -74,11 +74,11 @@ If your content is included in all versions of Enterprise, you need not include If your content only applies to GitHub.com, such as billing information, use this logic: ``` -{% if page.version == "dotcom" %}This is how you pay for your personal account, which is something you wouldn't do in Enterprise.{% endif %} +{% 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 page.version == "dotcom"` will include the content for Dotcom output and *only* Dotcom. +- `if currentVersion == "free-pro-team@latest"` will include the content for Dotcom output and *only* Dotcom. - `{% endif %}` ends the statement. #### Including content for *new Dotcom features* that will be included in Enterprise @@ -86,13 +86,13 @@ In this example: 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 page.version == "dotcom" or page.version ver_gt "2.6" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %} +{% 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 page.version == "dotcom"` will include the content for GitHub.com output. -- `or page.version ver_gt "2.6"` will include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+. +- `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 2.21, which means the content will be included for 2.7+. - `{% endif %}` ends the statement. #### Including content for *changed* Dotcom features that will also change in Enterprise @@ -100,13 +100,13 @@ In this example: 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 page.version == "dotcom" or page.version ver_gt "2.10" %}This is the new way of doing things {% else %}This is the old way of doing things {% endif %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "2.20" %}This is the new way of doing things {% else %}This is the old way of doing things {% endif %} ``` In this example: -- `if page.version == "dotcom"` will include the content for GitHub.com output. -- `or page.version ver_gt "2.6"` will include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+. +- `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 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. @@ -115,22 +115,23 @@ In this example: 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 page.version == 'dotcom' or page.version ver_gt "2.10" %} +{% if currentVersion == 'dotcom' or currentVersion ver_gt "2.20" %} This is the new way of doing things. -{% elsif page.version ver_gt "2.8" and page.version ver_lt "2.11" %} +{% endif %} +{% if currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "2.21" %} -This is the old way of doing things (which did not exist before 2.9). +This is the old way of doing things (which did not exist before 2.20). {% endif %} ``` In this example: -- `if page.version == "dotcom"` will include the content for GitHub.com output. -- `or page.version ver_gt "2.10"` will include the content for releases *after* Enterprise 2.10, which means the content will be included for 2.11+. -- `elsif page.version ver_gt "2.8" and page.version ver_lt "2.11"` means if the above is NOT true, and the version is either 2.9 or 2.10, then display the content that follows, `This is the old way of doing things`. No content will be displayed for versions older than 2.9. +- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output. +- `or currentVersion ver_gt "2.20"` will include the content for releases *after* Enterprise 2.20, which means the content will be included for 2.21+. +- `elsif currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "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 features* that don't exist on Dotcom @@ -138,13 +139,13 @@ In this example: 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 page.version != "dotcom" and page.version ver_gt "2.6" %}This is a brand new feature, admin-type people!{% endif %} +{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %}This is a brand new feature, admin-type people!{% endif %} ``` In this example: -- `if page.version != "dotcom"` will exclude the content for GitHub.com output. -- `and page.version ver_gt "2.6"` will *additionally* include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+. +- `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 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 @@ -152,12 +153,12 @@ In this example: 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 page.version != "dotcom" and page.version ver_gt "2.6" %}This is the new way of doing things, admins! {% else %}This is the old way of doing things, admins! {% endif %} +{% if currentVersion != "free-pro-team@latest" and 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 page.version != "dotcom"` will exclude the content for GitHub.com output. -- `and page.version ver_gt "2.6"` will *additionally* include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+. +- `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 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. diff --git a/contributing/permalinks.md b/contributing/permalinks.md index 9e91eb8fc026..07615c493847 100644 --- a/contributing/permalinks.md +++ b/contributing/permalinks.md @@ -1,15 +1,15 @@ # Permalinks -Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`productVersions` frontmatter](content#productversions). +Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`versions` frontmatter](content#versions). -For example, an article that is available in Dotcom and all Enterprise versions will have permalinks like the following: +For example, an article that is available in currently supported versions will have permalink URLs like the following: -* `/en/articles/set-up-git` -* `/en/enterprise/2.16/user/articles/set-up-git` -* `/en/enterprise/2.15/user/articles/set-up-git` -* `/en/enterprise/2.14/user/articles/set-up-git` -* `/en/enterprise/2.13/user/articles/set-up-git` +* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git` +* `/en/enterprise-server@2.22/github/getting-started-with-github/set-up-git` +* `/en/enterprise-server@2.21/github/getting-started-with-github/set-up-git` +* `/en/enterprise-server@2.20/github/getting-started-with-github/set-up-git` +* `/en/enterprise-server@2.19/github/getting-started-with-github/set-up-git` -An article that is only available in Dotcom will have just one permalink: +An article that is not available in Enterprise will have just one permalink: -* `/en/articles/githubs-billing-plans` +* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git` diff --git a/contributing/redirects.md b/contributing/redirects.md index e74839e1e481..14597b5a6789 100644 --- a/contributing/redirects.md +++ b/contributing/redirects.md @@ -8,22 +8,12 @@ Sometimes we change the name of an article but want its old URL to redirect to i ## External redirects -Sometimes the canonical home of some content moves outside the help site. For these types of redirects, we add entries to [/lib/external-redirects.json](/lib/external-redirects.json). +Sometimes the canonical home of some content moves outside the help site. For these types of redirects, we add entries to [/lib/redirects/external-redirects.json](/lib/redirects/external-redirects.json). ## Custom redirects -We also have custom routing code that dynamically handles things like moved [hidden pages](/content#hidden-pages) or deprecated products like GitHub Desktop Classic. This code lives in [/middleware/redirects.js](/middleware/redirects.js). +We also have custom routing code that automatically creates redirects under the hood for things like moved Admin guide pages. This code lives in [/lib/redirects/get-old-paths-from-permalink.js](/lib/redirects/get-old-paths-from-permalink.js). All redirects for the site are compiled when the server starts by [/lib/redirects/precompile.js](/lib/redirects/precompile.js). -## Autogenerated redirects +See [Links and image paths](content/README.md#links-and-image-paths) for info on how links and images are rewritten on the fly at page render time. -The site automatically generates a number of redirects under the hood: - -| Redirect from | Redirect to | Example -| -- | -- | -- | -| Path without a language prefix | Path with an English prefix | `https://help.github.com/articles/set-up-git` to `https://help.github.com/en/articles/set-up-git` -| Redirect without a language code | Path with an English prefix | `https://help.github.com/mac-set-up-git` to `https://help.github.com/en/articles/set-up-git/` -| Enterprise path without a version | Path with the latest version | `https://help.github.com/enterprise` to `https://help.github.com/en/enterprise/2.16` -| Enterprise path that includes `/guides/` | Path without `/guides/` | `https://help.github.com/enterprise/admin/guides/installation` to `https://help.github.com/en/enterprise/2.16/admin/installation` -| Desktop path that includes `/guides/` | Path without `/guides/` | `https://help.github.com/desktop/guides/contributing-to-projects` to `https://help.github.com/en/desktop/contributing-to-projects` - -See [Debugging](contribution/debugging.md) for info on viewing the redirects for any page. +See [Troubleshooting](contribution/troubleshooting.md#debugging-locally) for info on viewing the redirects for any page.