document npm run build step in development and troubleshooting guides

contributing/development.md

@@ -8,21 +8,24 @@ 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:
 
 ```sh
 git clone https://github.com/github/docs
 cd docs
 npm install
+npm run build
 npm start
 ```
 
 You should now have a running server! Visit [localhost:4000](http://localhost:4000) in your browser. It will automatically restart as you make changes to site content.
 
 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.
+
 ## Site structure
 
 This site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.ws/), another Ruby static site generator.

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