github · Octomerger · Oct 1, 2020 · Oct 1, 2020
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -85,6 +85,8 @@ You can use the GitHub user interface :pencil2: for some small changes, like fix
 ## Working in the github/docs repository
 Here's some information that might be helpful while working on a Docs PR:
 
+- [Development](/contributing/development.md) - This short guide describes how to get this app running on your local machine.
+
 - [Content markup reference](/contributing/content-markup-reference.md) - All of our content is written in GitHub-flavored Markdown, with some additional enhancements.
 
 - [Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines.

diff --git a/README.md b/README.md
@@ -7,16 +7,12 @@ GitHub's Docs team works on pre-production content in a private repo that regula
 In this article:
 - [Contributing](#contributing)
 - [READMEs](#readmes)
-- [Developing](#developing)
-- [Site structure](#site-structure)
-- [Error handling](#error-handling)
-- [Search](#search)
 - [License](#license)
 - [Contributors ✨](#contributors-)
 
 ## Contributing
 
-:memo: To find out how you can best contribute to GitHub's product documentation, see [CONTRIBUTING.md](/CONTRIBUTING.md).
+:memo: To find out how you can best contribute to GitHub's product documentation, see the [CONTRIBUTING](/CONTRIBUTING.md) guide.
 
 :mega: If you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
 
@@ -31,6 +27,7 @@ In this article:
 In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail:
 
 - [content/README.md](content/README.md)
+- [contributing/README.md](contributing/README.md)
 - [data/README.md](data/README.md)
 - [data/reusables/README.md](data/reusables/README.md)
 - [data/variables/README.md](data/variables/README.md)
@@ -44,61 +41,6 @@ In addition to the README you're reading right now, this repo includes other REA
 - [stylesheets/README.md](stylesheets/README.md)
 - [tests/README.md](tests/README.md)
 
-## Developing
-
-This site is powered by Node.js! :turtle: :rocket:
-
-You'll need **Node.js v12**  to run the site. If you're using nodenv (you can
-run `nodenv version` to find out which Node.js version you're on), read the
-[nodenv](#nodenv) section 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).
-
-Once you've installed Node.js, open up Terminal and run the following:
-
-```sh
-git clone https://github.com/github/docs-internal
-cd docs-internal
-npm install
-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.
-
-## Site structure
-
-This site was originally written in [Jekyll](https://jekyllrb.com/) and later
-[Nanoc](https://nanoc.ws/), both of which are Ruby static site generators.
-This site is now a dynamic Node.js webserver powered by Express, using middleware
-to add support for proper HTTP redirects, language header detection, and dynamic
-content generation to support the various flavors of GitHub's product documenation,
-like dotcom and GitHub Enterprise. For more context on why this change was made,
-see the [new help.github.com](https://github.com/github/product-documentation/tree/master/new-docs-site#static-vs-dynamic)
- proposal doc.
-
-The tech powering the site is now different, but many of the tried-and-true
-authoring conventions of the original Jekyll site have been preserved:
-
-- Content is written in Markdown files which live in the `content` directory.
-- Content can use the Liquid templating language.
-- Files in the `data` directory are available to templates via the `{% data %}` tag.
-- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter).
-- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported.
-
-See the [Content README](content) for more info.
-
-## Error handling
-
-Errors generated from requests will be sent to Sentry via `middlware/handle-errors.js`, and the `lib/failbot.js` client. This is a lightweight wrapper for sending exceptions to GitHub's Sentry instance.
-
-## Search
-
-This site's search functionality is powered by [Algolia](https://www.algolia.com), a third-party service.
-
-See [search.md](search.md) for details.
-
 ## License
 
 The GitHub product documentation in the assets, content, and data folders are licensed under a [CC-BY license](content/LICENSE).

diff --git a/contributing/readme.md → contributing/README.md b/contributing/readme.md → contributing/README.md
@@ -4,6 +4,7 @@ Check out our [contributing.md](../CONTRIBUTING.md) to see all the ways you can
 
 Here, you'll find additional information that might be helpful as you work on a pull request in this repo.
 
+- [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
 - [deployments](./deployments.md) - how our staging and production environments work

diff --git a/contributing/development.md b/contributing/development.md
@@ -0,0 +1,77 @@
+# Development
+
+This document describes the process for running this application on your local computer.
+
+## Getting started
+
+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).
+
+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 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.
+
+## 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.
+
+Today it's a dynamic Node.js webserver powered by Express, using [middleware](../middleware/README.md) to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of GitHub's product documentation, like GitHub.com and GitHub Enterprise Server.
+
+The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved:
+
+- Content is written in Markdown files, which live in the `content` directory.
+- Content can use the [Liquid templating language](liquid-helpers.md).
+- Files in the `data` directory are available to templates via the `{% data %}` tag.
+- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter).
+- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported.
+
+For more info about working with this site, check out these READMEs:
+
+- [content/README.md](../content/README.md)
+- [contributing/README.md](../contributing/README.md)
+- [data/README.md](../data/README.md)
+- [data/reusables/README.md](../data/reusables/README.md)
+- [data/variables/README.md](../data/variables/README.md)
+- [includes/liquid-tags/README.md](../includes/liquid-tags/README.md)
+- [includes/README.md](../includes/README.md)
+- [javascripts/README.md](../javascripts/README.md)
+- [layouts/README.md](../layouts/README.md)
+- [lib/liquid-tags/README.md](../lib/liquid-tags/README.md)
+- [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
+```
diff --git a/includes/liquid-tags/README.md b/includes/liquid-tags/README.md
@@ -2,4 +2,7 @@
 
 This directory contains templates for our custom Liquid tags.
 
-For more details, see [lib/liquid-tags/README.md](../../lib/liquid-tags/README.md).
+See also:
+
+- [lib/liquid-tags/README.md](../../lib/liquid-tags/README.md)
+- [contributing/liquid-helpers.md](../../contributing/liquid-helpers.md)
diff --git a/lib/liquid-tags/README.md b/lib/liquid-tags/README.md
@@ -1,5 +1,7 @@
 # Liquid Tags
 
+See also [contributing/liquid-helpers.md](../../contributing/liquid-helpers.md)
+
 This directory contains custom Liquid tags for outputting dynamic content. These custom tags exist for a few reasons:
 
 - Content and styling should be separated. Writers should not be concerned with writing or maintaining stylistic markup.