jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-23 21:07:12 -05:00
Code Issues Projects Releases Wiki Activity

Merge branch 'main' into onboarding

Browse Source
This commit is contained in:
Zeke Sikelianos
2020-10-06 00:08:05 -07:00
committed by GitHub
parent 9be6d1dd16 e00e1a2150
commit 5654ab4566
15 changed files with 119 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.github/config.yml vendored Normal file
View File

@@ -0,0 +1,11 @@
# Configuration for welcome - https://github.com/behaviorbot/welcome
# Configuration for new-issue-welcome - https://github.com/behaviorbot/new-issue-welcome
# Comment to be posted to on first time issues
newIssueWelcomeComment: >
Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the [contributing guidelines](https://github.com/github/docs/blob/main/CONTRIBUTING.md).
# Configuration for new-pr-welcome - https://github.com/behaviorbot/new-pr-welcome
# Comment to be posted to on PRs from first time contributors in your repository
newPRWelcomeComment: >
Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the [contributing guidelines](https://github.com/github/docs/blob/main/CONTRIBUTING.md).

2
.github/workflows/sync-algolia-search-indices.yml vendored
View File

@@ -15,7 +15,7 @@ jobs:
uses: actions/checkout@v2
- uses: actions/setup-node@v1
with:
node-version: "12.x"
node-version: 14.x
- name: cache node modules
uses: actions/cache@v1
with:

4
.github/workflows/test-translations.yml vendored
View File

@@ -19,7 +19,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache
@@ -57,7 +57,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache

4
.github/workflows/test-windows.yml vendored
View File

@@ -20,7 +20,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache
@@ -58,7 +58,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache

4
.github/workflows/test.yml vendored
View File

@@ -23,7 +23,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache
@@ -60,7 +60,7 @@ jobs:
- name: Setup node
uses: actions/setup-node@v1
with:
node-version: 12.x
node-version: 14.x
- name: Get npm cache directory
id: npm-cache

2
.node-version
View File

@@ -1 +1 @@
12.8.0
14.13.0

6
Dockerfile
View File

@@ -6,7 +6,7 @@
# INSTALLATION IMAGE
# A temporary image that installs production-only dependencies
FROM node:12-alpine as installation
FROM node:14-alpine as installation
ENV NODE_ENV production
WORKDIR /usr/src/docs
COPY package*.json ./
@@ -18,7 +18,7 @@ RUN npm ci
# BUNDLE IMAGE
# A temporary image that installs dependencies and builds the production-ready front-end bundles.
FROM node:12-alpine as bundles
FROM node:14-alpine as bundles
WORKDIR /usr/src/docs
# Install the files used to create the bundles
COPY package*.json ./
@@ -32,7 +32,7 @@ RUN npm ci && npm run build
# --------------------------------------------------------------------------------
# MAIN IMAGE
FROM node:12-alpine
FROM node:14-alpine
# Let's make our home
WORKDIR /usr/src/docs

128
content/README.md
View File

@@ -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:
A content file can have **two** types of versioning:
* 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:
```
{%- 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:
```
<a href="/articles/github-terms-of-service/" class="dotcom-only">GitHub's Terms of Service</a>
<a href="/github/site-policy/github-terms-of-service" class="dotcom-only">GitHub's Terms of Service</a>
```
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.
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.

1
content/rest/reference/permissions-required-for-github-apps.md
View File

@@ -168,7 +168,6 @@ _Search_
{% if currentVersion == "free-pro-team@latest" %}
- [`DELETE /repos/:owner/:repo/vulnerability-alerts`](/v3/repos/#disable-vulnerability-alerts) (:write)
{% endif %}
- [`POST /user/repos`](/v3/repos/#create-a-repository-for-the-authenticated-user) (:write)
- [`PATCH /user/repository_invitations/:invitation_id`](/v3/repos/invitations/#accept-a-repository-invitation) (:write)
- [`DELETE /user/repository_invitations/:invitation_id`](/v3/repos/invitations/#decline-a-repository-invitation) (:write)

26
contributing/development.md
View File

@@ -8,7 +8,7 @@ This site is powered by Node.js! :sparkles: :turtle: :rocket: :sparkles:
It runs on macOS, Windows, and Linux environments.
You'll need **Node.js v12** to run the site. If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) below for instructions on switching to Node.js 12. If you're not using `nodenv`, the best way to install Node.js is to [download the LTS installer from nodejs.org](https://nodejs.org).
You'll need **Node.js v14** to run the site. If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) for instructions on switching Node.js versions. If you're not using `nodenv`, the best way to install Node.js is to [download the LTS installer from nodejs.org](https://nodejs.org).
Once you've installed Node.js (which includes the popular `npm` package manager), open Terminal and run the following:
@@ -52,26 +52,4 @@ For more info about working with this site, check out these READMEs:
- [middleware/README.md](../middleware/README.md)
- [script/README.md](../script/README.md)
- [stylesheets/README.md](../stylesheets/README.md)
- [tests/README.md](../tests/README.md)
## `nodenv`
[nodenv](https://github.com/nodenv/nodenv) is a tool for managing multiple Node.js versions on your local machine. It is **not required** to run this app, but you may already have it installed if you've worked on other projects that use Node.js.
To install Node.js 12 and make it your default version, run this command:
```sh
nodenv install 12.8.0 && nodenv global 12.8.0
```
You may sometimes see a warning when running npm scripts with nodenv:
```sh
npm WARN lifecycle The node binary used for scripts is [...] but npm is using [...]
```
This is due to nodenv's overriding behavior. To silence this harmless warning, the [nodenv docs](https://github.com/nodenv/nodenv/wiki/FAQ#npm-warning-about-mismatched-binaries) recommend running the following command from any directory:
```sh
npm config set scripts-prepend-node-path auto
```
- [tests/README.md](../tests/README.md)

45
contributing/liquid-helpers.md
View File

@@ -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.

40
contributing/node-versions.md
View File

@@ -1,26 +1,32 @@
## Node Versions
# Node Versions
The site currently runs on Node.js v12, the [Active LTS version](https://nodejs.org/en/about/releases/) that will be supported until 2020-10-20.
The site currently runs on Node.js v14, the [Active LTS version](https://nodejs.org/en/about/releases/) from 2020-10-27 to 2021-10-26.
When updating to a new Node.js version, consider the following files:
- The `engines.node` entry in `package.json`
- The `.node-version` file used by [nodenv](https://github.com/nodenv/nodenv), a tool for managing multiple Node.js versions on your machine.
- The `.github/*.workflow` Actions files
- The `Dockerfile` that can be used for deployments
- This README!
- [ ] The `engines.node` entry in `package.json`
- [ ] The `.node-version` file used by [nodenv](https://github.com/nodenv/nodenv), a tool for managing multiple Node.js versions on your machine.
- [ ] The `.github/*.workflow` Actions files
- [ ] The `Dockerfile` that can be used for deployments
- [ ] The `contributing/development.md` guide
- [ ] The `contributing/node-versions.md` file
### `nodenv`
## `nodenv`
[nodenv](https://github.com/nodenv/nodenv) is a tool for managing multiple
Node.js versions on your local machine. It is **not required** to run the
docs-internal app, but you may already have it installed if you've worked on other
internal GitHub projects that use Node.js.
[nodenv](https://github.com/nodenv/nodenv) is a tool for managing multiple Node.js versions on your local machine. It is **not required** to run this app, but you may already have it installed if you've worked on other projects that use Node.js.
To install Node.js 12 and make it your default version, run this command:
If you're using macOS, run this command to get the latest:
```
brew upgrade nodenv node-build
```
If you're using another operating system, or did not use Homebrew to install nodenv, see these [upgrade instructions](https://github.com/nodenv/nodenv#installation).
To install Node.js 14 and make it your default version, run this command:
```sh
nodenv install 12.8.0 && nodenv global 12.8.0
nodenv install 14.13.0 && nodenv global 14.13.0
```
You may sometimes see a warning when running npm scripts with nodenv:
@@ -29,10 +35,8 @@ You may sometimes see a warning when running npm scripts with nodenv:
npm WARN lifecycle The node binary used for scripts is [...] but npm is using [...]
```
This is due to nodenv's overriding behavior. To silence this harmless warning,
the [nodenv docs](https://github.com/nodenv/nodenv/wiki/FAQ#npm-warning-about-mismatched-binaries)
recommend running the following command from any directory:
This is due to nodenv's overriding behavior. To silence this harmless warning, the [nodenv docs](https://github.com/nodenv/nodenv/wiki/FAQ#npm-warning-about-mismatched-binaries) recommend running the following command from any directory:
```sh
npm config set scripts-prepend-node-path auto
```
```

18
contributing/permalinks.md
View File

@@ -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`

18
contributing/redirects.md
View File

@@ -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.

2
package.json
View File

@@ -140,7 +140,7 @@
"pa11y-test": "start-server-and-test browser-test-server 4001 pa11y-ci"
},
"engines": {
"node": "8 - 12"
"node": "12 - 14"
},
"repository": "https://github.com/github/docs",
"standard": {