Break out Installation into top-level doc section (reactjs#452)

alexkrolick · gaearon · commit 7fafb9f916ca · 2017-12-23T15:37:23.000Z
* Break out Installation into top-level doc section

* Update navigation (prev/next, nav tree)

- Move Installation section to top
- Add next/prev to install pages

* add links to other install options from try react page

* fix markdown link

* Clarify that Quick Start and Install are optional "next steps"

* Add top-level CDN page

This is useful for Codepen and other Unpkg-y setups

* Add link to Tutorial from Try React

* Update CRA link in tutorial

* Make Try React subheader a proper sentence

* Add "minimal"

* Explain local dev setup is more work than Codepen etc

* Fix typos

* Add : between headings

* add note that CRA is not lightweight

* fix typo

* Update add-react-to-a-new-app.md

* Update add-react-to-a-new-app.md

* Remove the Bower note

* Update try-react.md

* Tweak wording

* Use direct link
diff --git a/content/docs/add-react-to-a-new-app.md b/content/docs/add-react-to-a-new-app.md
@@ -0,0 +1,47 @@
+---
+id: add-react-to-a-new-app
+title: Add React to a New Application
+permalink: docs/add-react-to-a-new-app.html
+prev: try-react.html
+next: add-react-to-an-existing-app.html
+---
+
+The easiest way to get started on a new React project is by using a starter kit.
+
+> Note:
+> 
+> Check out the [Try React](/docs/try-react.html) page if you are looking for lightweight environments to experiment with React.
+> The options on this page are designed to help bootstrap single-page applications with linting, testing, bundling, production optimizations, and more.
+
+## Create React App
+
+[Create React App](http://github.com/facebookincubator/create-react-app) is the best way to start building a new React single page application. It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. You’ll need to have Node >= 6 on your machine.
+
+```bash
+npm install -g create-react-app
+create-react-app my-app
+
+cd my-app
+npm start
+```
+
+If you have npm 5.2.0+ installed, you may use [npx](https://www.npmjs.com/package/npx) instead.
+
+```bash
+npx create-react-app my-app
+
+cd my-app
+npm start
+```
+
+Create React App doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want. It uses build tools like [Babel](http://babeljs.io/) and [webpack](https://webpack.js.org/) under the hood, but works with zero configuration.
+
+When you're ready to deploy to production, running `npm run build` will create an optimized build of your app in the `build` folder. You can learn more about Create React App [from its README](https://github.com/facebookincubator/create-react-app#create-react-app-) and the [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#table-of-contents).
+
+## Other Starter Kits
+
+See the Community section for a list of [starter kits](/community/starter-kits.html).
+
+## Advanced
+
+If you prefer to configure a project manually, see [Installing React](/docs/add-react-to-an-existing-app.html#installing-react) in the next section.
diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md
@@ -1,60 +1,11 @@
 ---
-id: installation
-title: Installation
-permalink: docs/installation.html
-redirect_from:
-  - "download.html"
-  - "downloads.html"
-  - "docs/tooling-integration.html"
-  - "docs/package-management.html"
-  - "docs/language-tooling.html"
-  - "docs/environments.html"
-next: hello-world.html
+id: add-react-to-an-existing-app
+title: Add React to an Existing Application
+permalink: docs/add-react-to-an-existing-app.html
+prev: add-react-to-a-new-app.html
+next: cdn-links.html
 ---
 
-React is flexible and can be used in a variety of projects. You can create new apps with it, but you can also gradually introduce it into an existing codebase without doing a rewrite.
-
-Here are a couple of ways to get started:
-
-* [Try React](#trying-out-react)
-* [Create a New App](#creating-a-new-application)
-* [Add React to an Existing App](#adding-react-to-an-existing-application)
-
-## Trying Out React
-
-If you're just interested in playing around with React, you can use CodePen. Try starting from [this Hello World example code](http://codepen.io/gaearon/pen/rrpgNB?editors=0010). You don't need to install anything; you can just modify the code and see if it works.
-
-If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production.
-
-If you want to use it for a full application, there are two popular ways to get started with React: using Create React App, or adding it to an existing application.
-
-## Creating a New Application
-
-[Create React App](http://github.com/facebookincubator/create-react-app) is the best way to start building a new React single page application. It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. You’ll need to have Node >= 6 on your machine.
-
-```bash
-npm install -g create-react-app
-create-react-app my-app
-
-cd my-app
-npm start
-```
-
-If you have npm 5.2.0+ installed, you may use [npx](https://www.npmjs.com/package/npx) instead.
-
-```bash
-npx create-react-app my-app
-
-cd my-app
-npm start
-```
-
-Create React App doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want. It uses build tools like [Babel](http://babeljs.io/) and [webpack](https://webpack.js.org/) under the hood, but works with zero configuration.
-
-When you're ready to deploy to production, running `npm run build` will create an optimized build of your app in the `build` folder. You can learn more about Create React App [from its README](https://github.com/facebookincubator/create-react-app#create-react-app-) and the [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#table-of-contents).
-
-## Adding React to an Existing Application
-
 You don't need to rewrite your app to start using React.
 
 We recommend adding React to a small part of your application, such as an individual widget, so you can see if it works well for your use case.
@@ -134,34 +85,4 @@ Learn [how to tell if your website is serving the right version of React](/docs/
 
 ### Using a CDN
 
-If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide single-file distributions in `umd` folders, which are hosted on a CDN:
-
-```html
-<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
-<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
-```
-
-The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at:
-
-```html
-<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
-<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
-```
-
-To load a specific version of `react` and `react-dom`, replace `16` with the version number.
-
-If you use Bower, React is available via the `react` package.
-
-#### Why the `crossorigin` Attribute?
-
-If you serve React from a CDN, we recommend to keep the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute set:
-
-```html
-<script crossorigin src="..."></script>
-```
-
-We also recommend to verify that the CDN you are using sets the `Access-Control-Allow-Origin: *` HTTP header:
-
-![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png)
-
-This enables a better [error handling experience](/blog/2017/07/26/error-handling-in-react-16.html) in React 16 and later.
+If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide single-file distributions in `umd` folders. See the [CDN](/docs/cdn-links.html) page for links.
diff --git a/content/docs/cdn-links.md b/content/docs/cdn-links.md
@@ -0,0 +1,37 @@
+---
+id: cdn-links
+title: CDN Links
+permalink: docs/cdn-links.html
+prev: add-react-to-an-existing-app.html
+next: hello-world.html
+---
+
+The UMD builds of React and ReactDOM are available over a CDN.
+
+```html
+<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
+```
+
+The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at:
+
+```html
+<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+```
+
+To load a specific version of `react` and `react-dom`, replace `16` with the version number.
+
+### Why the `crossorigin` Attribute?
+
+If you serve React from a CDN, we recommend to keep the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute set:
+
+```html
+<script crossorigin src="..."></script>
+```
+
+We also recommend to verify that the CDN you are using sets the `Access-Control-Allow-Origin: *` HTTP header:
+
+![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png)
+
+This enables a better [error handling experience](/blog/2017/07/26/error-handling-in-react-16.html) in React 16 and later.
diff --git a/content/docs/hello-world.md b/content/docs/hello-world.md
@@ -2,7 +2,7 @@
 id: hello-world
 title: Hello World
 permalink: docs/hello-world.html
-prev: installation.html
+prev: cdn-links.html
 next: introducing-jsx.html
 redirect_from:
   - "docs/"
@@ -12,7 +12,7 @@ redirect_from:
   - "docs/getting-started-zh-CN.html"
 ---
 
-The easiest way to get started with React is to use [this Hello World example code on CodePen](codepen://hello-world). You don't need to install anything; you can just open it in another tab and follow along as we go through examples. If you'd rather use a local development environment, check out the [Installation](/docs/installation.html) page.
+The easiest way to get started with React is to use [this Hello World example code on CodePen](codepen://hello-world). You don't need to install anything; you can just open it in another tab and follow along as we go through examples. If you'd rather use a local development environment, check out the [Installation](/docs/try-react.html) section.
 
 The smallest React example looks like this:
 
diff --git a/content/docs/nav.yml b/content/docs/nav.yml
@@ -1,7 +1,15 @@
+- title: Installation
+  items:
+    - id: try-react
+      title: Try React
+    - id: add-react-to-a-new-app
+      title: Add React to a New App
+    - id: add-react-to-an-existing-app
+      title: Add React to an Existing App
+    - id: cdn-links
+      title: CDN Links
 - title: Quick Start
   items:
-    - id: installation
-      title: Installation
     - id: hello-world
       title: Hello World
     - id: introducing-jsx
diff --git a/content/docs/try-react.md b/content/docs/try-react.md
@@ -0,0 +1,41 @@
+---
+id: try-react
+title: Try React
+permalink: docs/try-react.html
+next: add-react-to-a-new-app.html
+redirect_from:
+  - "docs/installation.html"
+  - "download.html"
+  - "downloads.html"
+  - "docs/tooling-integration.html"
+  - "docs/package-management.html"
+  - "docs/language-tooling.html"
+  - "docs/environments.html"
+---
+
+Try React online or set up your local development environment.
+
+## Online
+
+If you're just interested in playing around with React, you can use an online code playground. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s/new).
+
+## Minimal HTML Template
+
+If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production.
+
+## Next Steps
+
+### Quick Start
+
+- Head over to the [Quick Start](/docs/hello-world.html) section for a step-by-step introduction to React concepts.
+
+- Try the [Tutorial](/tutorial/tutorial.html) for a hands-on practical example.
+
+### Complete Development Environment
+
+The lightweight solutions above are the best fit if you are new to React or just experimenting.
+
+When you are ready to build your first application with React, check out the install guides below. These setups are designed to get you up and running with a great developer experience and are ready for production. They include linting, testing, and optimizations built-in; however, they require more time and disk space to set up and install.
+
+- [Add React to a New App](/docs/add-react-to-a-new-app.html): Create a new app with a fully-featured starter kit.
+- [Add React to an Existing App](/docs/add-react-to-a-new-app.html): Add React to a build system or a larger app.
diff --git a/content/tutorial/tutorial.md b/content/tutorial/tutorial.md
@@ -53,7 +53,7 @@ This is more work, but lets you work from the comfort of your editor.
 If you want to do it, here are the steps to follow:
 
 1. Make sure you have a recent version of [Node.js](https://nodejs.org/en/) installed.
-2. Follow the [installation instructions](/docs/installation.html#creating-a-new-application) to create a new project.
+2. Follow the [installation instructions](/docs/add-react-to-a-new-app.html) to create a new project.
 
 ```bash
 npm install -g create-react-app
diff --git a/src/components/LayoutFooter/Footer.js b/src/components/LayoutFooter/Footer.js
@@ -62,13 +62,9 @@ const Footer = ({layoutHasSidebar = false}: {layoutHasSidebar: boolean}) => (
           <FooterNav layoutHasSidebar={layoutHasSidebar}>
             <MetaTitle onDark={true}>Docs</MetaTitle>
             {sectionListDocs.map(section => {
-              // Skip the Installation page for Quick Start
-              const defaultItem =
-                section.items[0].id === 'installation'
-                  ? section.items[1].id
-                  : section.items[0].id;
+              const defaultItem = section.items[0];
               return (
-                <FooterLink to={`/docs/${defaultItem}.html`}>
+                <FooterLink to={`/docs/${defaultItem.id}.html`}>
                   {section.title}
                 </FooterLink>
               );
