Better GH Pages guide

Author: gaearon

packages/react-scripts/template/README.md

@@ -941,7 +941,9 @@ This will let Create React App correctly infer the root path to use in the gener
 
 >Note: this feature is available with `[email protected]` and higher.
 
-**THE BELOW STEP IS IMPORTANT!**<br>
+#### Step 1: Add `homepage` to `package.json`
+
+**The below step is important!**<br>
 **If your skip it, your app will not deploy correctly.**
 
 Open your `package.json` and add a `homepage` field:
@@ -952,7 +954,7 @@ Open your `package.json` and add a `homepage` field:
 
 Create React App uses the `homepage` field to determine the root URL in the built HTML file.
 
-**Have you added the `homepage` field? Then let's move on.**
+#### Step 2: Install `gh-pages` and add `deploy` to `scripts` in `package.json`
 
 Now, whenever you run `npm run build`, you will see a cheat sheet with instructions on how to deploy to GitHub Pages.
 
@@ -974,17 +976,28 @@ Add the following script in your `package.json`:
 
 (Note: the lack of whitespace is intentional.)
 
+#### Step 3: Deploy the site by running `npm run deploy`
+
 Then run:
 
 ```sh
 npm run deploy
 ```
 
-**If you see 404 errors for JS and CSS, re-read the note at the beginning of this section saying "THE BELOW STEP IS IMPORTANT".**
+#### Step 4: Ensure your project's settings use `gh-pages`
+
+Finally, make sure **GitHub Pages** option in your GitHub project settings is set to use the `gh-pages` branch:
+
+<img src="http://i.imgur.com/HUjEr9l.png" width="500" alt="gh-pages branch setting">
+
+#### Step 5: Optionally, configure the domain
 
 You can configure a custom domain with GitHub Pages by adding a `CNAME` file to the `public/` folder.
 
-Note that GitHub Pages doesn't support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions:
+#### Notes on client-side routing
+
+GitHub Pages doesn't support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions:
+
 * You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to `hashHistory` for this effect, but the URL will be longer and more verbose (for example, `http://user.github.io/todomvc/#/todos/42?_k=yknaj`). [Read more](https://github.com/reactjs/react-router/blob/master/docs/guides/Histories.md#histories) about different history implementations in React Router.
 * Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your `index.html` page with a special redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages).