Merge branch 'main' into codespaces

contributing/README.md

@@ -6,7 +6,7 @@ Here, you'll find additional information that might be helpful as you work on a
 
 - [development](./development.md) - steps for getting this app running on your local machine
 - [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
-- [content style guide](./content-style-guide) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
+- [content style guide](./content-style-guide.md) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
 - [deployments](./deployments.md) - how our staging and production environments work
 - [liquid helpers](./liquid-helpers.md) - using liquid helpers for versioning in our docs
 - [localization checklist](./localization-checklist.md) - making sure your content is ready to be translated

contributing/content-markup-reference.md

@@ -64,7 +64,7 @@ Octicons are icons used across GitHub’s interface. We reference Octicons when
 
 `{% octicon "<name of octicon>" %}`  
 `{% octicon "plus" %}`
-`{% octicon "plus" aria-label="The plus icon"}`
+`{% octicon "plus" aria-label="The plus icon" %}`
 
 ## Operating system tags
 

contributing/content-style-guide.md

@@ -2,7 +2,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 [GitHub Brand Guide](https://brand.github.com/content/) first, then the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). For markup specific to source content on docs.github.com, see our [markup reference guide](content-markup-reference.md).
+These guidelines are specific to GitHub’s documentation. For general style questions or guidance on topics not covered here, see the [GitHub Brand Guide](https://brand.github.com/content/) first, then 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).
 
 ## Table of contents <!-- omit in toc -->
 - [The GitHub Docs approach to style](#the-github-docs-approach-to-style)
@@ -132,7 +132,7 @@ schedule:
 ## Headers
 
 Use H3 for headers, and H4 for subheaders. When referring to headers, surround the header name with quotation marks.
-- **Use:** Under “User licences”, view your total licenses.
+- **Use:** Under “User licenses”, view your total licenses.
 
 To orient readers and help them understand if the section is relevant to them, include introductory content after a header - don’t locate a subheader directly following a header.
 
@@ -140,7 +140,7 @@ To orient readers and help them understand if the section is relevant to them, i
 
 ### Alt text
 
-Every image must include an alt attribute that provides a complete description of the image for the user. For more information, see “[Images, image maps, and multimedia](https://docs.microsoft.com/en-us/style-guide/accessibility/graphics-design-media#images-image-maps-and-multimedia)” in Microsoft’s Style Guide.
+Every image must include an alt attribute that provides a complete description of the image for the user. For more information, see “[Images, image maps, and multimedia](https://docs.microsoft.com/style-guide/accessibility/graphics-design-media#images-image-maps-and-multimedia)” in Microsoft’s Style Guide.
 
 ### Filenames
 
@@ -170,9 +170,9 @@ GitHub Brand Guide:
 - [People and communities](https://brand.github.com/content/grammar#people-and-communities)
 
 The Microsoft Style Guide offers resources on bias-free communication, accessibility terms, and writing for all abilities:
-- [Bias-free communication](https://docs.microsoft.com/en-us/style-guide/bias-free-communication)
-- [Writing for all abilities](https://docs.microsoft.com/en-us/style-guide/accessibility/writing-all-abilities)
-- [Accessibility terms](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms)
+- [Bias-free communication](https://docs.microsoft.com/style-guide/bias-free-communication)
+- [Writing for all abilities](https://docs.microsoft.com/style-guide/accessibility/writing-all-abilities)
+- [Accessibility terms](https://docs.microsoft.com/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms)
 
 More resources for learning about inclusive and accessible language and style:
 - [18F Content Guide on Inclusive Language](https://content-guide.18f.gov/inclusive-language/)
@@ -257,7 +257,7 @@ Take care to distinguish between product names and product elements. For more in
 
 ## Punctuation
 
-Follow standard American English punctuation rules. For more guidance, see “[Punctuation](https://brand.github.com/content/grammar#punctuation)” in GitHub’s Brand Guide and “[Punctuation](https://docs.microsoft.com/en-us/style-guide/punctuation)” in the Microsoft Style Guide.
+Follow standard American English punctuation rules. For more guidance, see “[Punctuation](https://brand.github.com/content/grammar#punctuation)” in GitHub’s Brand Guide and “[Punctuation](https://docs.microsoft.com/style-guide/punctuation)” in the Microsoft Style Guide.
 
 ## Reusables and variables
 Use reusable strings for individual nouns (e.g. product names) or for complete sentences or paragraphs. Sentence fragments and phrases should not be contained in reusable strings as they can cause problems when content is localized. For more information, see the data directory in the github/docs repository and the “Product names” section of this document.
@@ -272,7 +272,7 @@ A table’s contents should be clear from the preceding content - avoid unneeded
 
 Use quotation marks around article titles, whether the article is hosted on GitHub Docs or elsewhere. Do not include quotation marks around the names of external sites.
 
-For further guidance, see “[Formatting titles](https://docs.microsoft.com/en-us/style-guide/text-formatting/formatting-titles)” in Microsoft’s Style Guide.
+For further guidance, see “[Formatting titles](https://docs.microsoft.com/style-guide/text-formatting/formatting-titles)” in Microsoft’s Style Guide.
 
 ## User interface elements
 
@@ -338,15 +338,15 @@ GitHub Brand Guide:
 - [Referring to GitHub features and product elements](https://brand.github.com/content/terminology/#referring-to-github-features-and-product-elements)
 - [Page names and UI references](https://brand.github.com/content/grammar#page-names-and-ui-references)
 Microsoft Style Guide:
-- [Formatting text in instructions](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions)
+- [Formatting text in instructions](https://docs.microsoft.com/style-guide/procedures-instructions/formatting-text-in-instructions)
 
 ## Voice and tone
 
-Use clear, simple language that’s approachable and accessible for a wide range of readers. For more information, see “[Voice](https://brand.github.com/content/voice/)” in GitHub’s Brand Guide. To learn more about writing approachable content, see “[Microsoft's brand voice: Above all, simple and human](https://docs.microsoft.com/en-us/style-guide/brand-voice-above-all-simple-human) and “[Top 10 tips for Microsoft style and voice](https://docs.microsoft.com/en-us/style-guide/top-10-tips-style-voice).”
+Use clear, simple language that’s approachable and accessible for a wide range of readers. For more information, see “[Voice](https://brand.github.com/content/voice)” in GitHub’s Brand Guide. To learn more about writing approachable content, see “[Microsoft's brand voice: Above all, simple and human](https://docs.microsoft.com/style-guide/brand-voice-above-all-simple-human) and “[Top 10 tips for Microsoft style and voice](https://docs.microsoft.com/style-guide/top-10-tips-style-voice).”
 
 ## Word choice and terminology
 
-For general guidance and GitHub-specific terms, see “[Terminology](https://brand.github.com/content/terminology)” and “[Words that can be tricky](https://brand.github.com/content/grammar#words-that-can-be-tricky)” in GitHub’s Brand Guide. For more detailed guidance, see the “[A-Z word list](https://docs.microsoft.com/en-us/style-guide)” in Microsoft’s style guide.
+For general guidance and GitHub-specific terms, see “[Terminology](https://brand.github.com/content/terminology)” and “[Words that can be tricky](https://brand.github.com/content/grammar#words-that-can-be-tricky)” in GitHub’s Brand Guide. For more detailed guidance, see the “[A-Z word list](https://docs.microsoft.com/style-guide)” in Microsoft’s style guide.
 
 ### Abbreviations
 

contributing/development.md

@@ -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 version 12 or 14 to run the site. To install Node.js, [download the "LTS" installer from nodejs.org](https://nodejs.org). If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) for instructions on switching Node.js versions. 
+You'll need Node.js version 12 or 14 to run the site. To install Node.js, [download the "LTS" installer from nodejs.org](https://nodejs.org). If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) for instructions on switching Node.js versions.
 
 Once you've installed Node.js (which includes the popular `npm` package manager), open Terminal and run the following:
 
@@ -16,6 +16,7 @@ Once you've installed Node.js (which includes the popular `npm` package manager)
 git clone https://github.com/github/docs
 cd docs
 npm install
+npm run build
 npm start
 ```
 
@@ -23,6 +24,8 @@ You should now have a running server! Visit [localhost:4000](http://localhost:40
 
 When you're ready to stop your local server, type <kbd>CTRL</kbd><kbd>c</kbd> in your terminal window.
 
+Note that `npm run build` is a one-time step that create static assets.
+
 ### Using GitHub Codespaces
 
 As an alternative, you can simply use [GitHub Codespaces](https://github.com/features/codespaces).

contributing/localization-checklist.md

@@ -26,7 +26,7 @@ Use the following checklist to help make your files more translation-friendly. F
 | Guideline | Avoid | Use instead |
 | --------- | ----- | ----------- |
 | Avoid country specific information. | 800 numbers, addresses, etc. | If necessary, mention what countries the information applies to. |
-| Avoid the excessive use of stacked modifiers (Noun strings). This can lead to incorrect translations because it is not easy to tell what modifies what. | “public repository default source settings” or “Oauth app access restrictions” | "Default source settings for the public repository"  or "restrictions for Oath app access." If using a stacked modifier is essential, make sure the background information and context are clear so the linguist understands what is the noun that is being modified. |
+| Avoid the excessive use of stacked modifiers (Noun strings). This can lead to incorrect translations because it is not easy to tell what modifies what. | “public repository default source settings” or “OAuth app access restrictions” | "Default source settings for the public repository"  or "restrictions for OAuth app access." If using a stacked modifier is essential, make sure the background information and context are clear so the linguist understands what is the noun that is being modified. |
 | Avoid invisible plurals. | "Program update" or "File retrieval". Is this an update of one program or a general procedure for multiple programs?  For "File retrieval", Are you retrieving one file or all of them? | Write the sentence more clearly or provide additional context to eliminate ambiguity that can result in an incorrect translation. |
 | Avoid nominalization. | "To reach a conclusion" | Use "Conclude." |
 | Avoid using ambiguous modal auxiliary verbs. | May, might, ought, could, used to, etc. | Be more clear when writing to avoid ambiguity. |

contributing/node-versions.md

@@ -1,6 +1,6 @@
 # Node Versions
 
-In [development](contributing/development.md) enviroments this site will run on Node.js versions `12 - 14`.
+In [development](contributing/development.md) environments this site will run on Node.js versions `12 - 14`.
 
 In [staging and production](contributing/deployments.md) environments this site runs on Node.js 14, the [Active LTS version](https://nodejs.org/en/about/releases/) from 2020-10-27 to 2021-10-26).
 

contributing/permalinks.md

@@ -13,3 +13,9 @@ For example, an article that is available in currently supported versions will h
 An article that is not available in Enterprise will have just one permalink:
 
 * `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
+
+**If you are a content contributor:** You don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article you can just use its relative location:
+
+* `/github/getting-started-with-github/set-up-git`
+
+*(Please note that using a hard-coded link or supported version will result in an error when your submitted PR is automatically tested)*

contributing/troubleshooting.md

@@ -1,5 +1,6 @@
-# Troubleshooting status checks <!-- omit in toc -->
+# Troubleshooting <!-- omit in toc -->
 
+- [Troubleshooting server tests that fail locally but pass in CI](#troublshooting-server-tests-that-fail-locally-but-pass-in-ci)
 - [Troubleshooting stalled deployments and CI](#troubleshooting-stalled-deployments-and-ci)
   - [Staging deployment stalled](#staging-deployment-stalled)
   - [CI stalled or stuck](#ci-stalled-or-stuck)
@@ -11,7 +12,13 @@
 - [Check external links](#check-external-links)
 - [Debugging locally](#debugging-locally)
 
-## Troubleshooting stalled deployments and CI
+## Troubleshooting
+
+### Troubleshooting server tests that fail locally but pass in CI
+
+If you run the tests locally and get failures in `tests/rendering/server.js` around static assets, stylesheets, and/or the client-side JavaScript bundle, but **the same tests pass in CI** on a PR, you likely need to run `npm run build`. This is a one-time command that creates static assets locally.
+
+See [`development.md`](./development.md) for more info.
 
 ### Staging deployment stalled
 If a staging deployment is pending for more than 5-10min, try the following:
@@ -83,7 +90,7 @@ Again, you should see more information about the error either in your browser or
 
 The `check internal links` test reports any broken links on the site, including images. The test reports the URL of the broken link, _not_ the file that includes that link, so you'll need to search the `docs` repository to find the file.
 
-Broken images include `assets/images/` in the URL and are often caused by images being versioned for previous versions of GHES but not uploaded to the appropriate folder in S3. Search the `docs` repository for the file name (e.g., `assets/images/help/repository/security-tab.png`), then make sure the image is versioned correctly in each result. If the image is in a reusable, you'll also need to search for each occurence of that reusable. If the image is versioned correctly, upload the image to the appropriate folder(s) in S3.
+Broken images include `assets/images/` in the URL and are often caused by images being versioned for previous versions of GHES but not uploaded to the appropriate folder in S3. Search the `docs` repository for the file name (e.g., `assets/images/help/repository/security-tab.png`), then make sure the image is versioned correctly in each result. If the image is in a reusable, you'll also need to search for each occurrence of that reusable. If the image is versioned correctly, upload the image to the appropriate folder(s) in S3.
 
 For broken links to articles on our site, find the file that contains the link by searching the `docs` repository for the file name (e.g., `incorporating-feedback-in-your-pull-request`). Try the following fixes:
 
@@ -107,4 +114,4 @@ During development, you can visit any page on `http://localhost:4000` and add `?
 | `permalinks` | Shows all [permalinks](contributing/permalinks.md) that the site is generating for the page.
 | `redirect_from` | Shows the hardcoded redirects in the [`redirect_from` frontmatter](content#redirect_from).
 | `redirects` | Shows all redirects that the site is generating for the page.
-| `includesPlatformSpecificContent` | Shows whether the site detects any [platform-specific content](#operating-system-tags) on the page.
+| `includesPlatformSpecificContent` | Shows whether the site detects any [platform-specific content](#operating-system-tags) on the page.