Merge pull request #3155 from taion/improve-redirect-docs

Improve redirect docs

docs/API.md

@@ -460,18 +460,7 @@ All the same props as [Route](#route) except for `path`.
 ### `<IndexRedirect>`
 An `<IndexRedirect>` allows you to redirect from the URL of a parent route to another route. They can be used to allow a child route to serve as the default route for its parent, while still keeping a distinct URL.
 
-#### Example
-```js
-<Router>
-  <Route path="/" component={App}>
-    <IndexRedirect to="groups" />
-    {/* If no child route is matched, will redirect to 'groups' */}
-
-    <Route path="groups" component={Groups} />
-    <Route path="users" component={Users} />
-  </Route>
-</Router>
-```
+Please see the [Index Routes guide](/docs/guides/IndexRoutes.md).
 
 #### Props
 All the same props as [Redirect](#redirect) except for `from`.

docs/guides/IndexRoutes.md

@@ -37,6 +37,43 @@ the router allows you to have `Home` be a first class route component with
 Now `App` can render `{this.props.children}` and we have a first-class
 route for `Home` that can participate in routing.
 
+## Index Redirects
+
+Suppose your basic route configuration looks like:
+
+```js
+<Route path="/" component={App}>
+  <Route path="welcome" component={Welcome} />
+  <Route path="about" component={About} />
+</Route>
+```
+
+Suppose you want to redirect `/` to `/welcome`. To do this, you need to set up
+an index route that does the redirect. To do this, use the `<IndexRedirect>`
+component:
+
+```js
+<Route path="/" component={App}>
+  <IndexRedirect to="/welcome" />
+  <Route path="welcome" component={Welcome} />
+  <Route path="about" component={About} />
+</Route>
+```
+
+This is equivalent to setting up an index route with just an `onEnter` hook
+that redirects the user. You would set this up with plain routes as:
+
+```js
+const routes = [{
+  path: '/', component: App,
+  indexRoute: { onEnter: (nextState, replace) => replace('/welcome') },
+  childRoutes: [
+    { path: 'welcome', component: Welcome },
+    { path: 'about', component: About }
+  ]
+}]
+```
+
 ## Index Links
 
 If you were to `<Link to="/">Home</Link>` in this app, it would always

docs/guides/RouteConfiguration.md

@@ -175,14 +175,16 @@ Continuing with our example above, if a user clicked on a link to `/about` from
   - `onLeave` on the `/inbox` route
   - `onEnter` on the `/about` route
 
-### Alternate Configuration
+### Configuration with Plain Routes
 
 Since [routes](/docs/Glossary.md#route) are usually nested, it's useful to use a concise nested syntax like [JSX](https://facebook.github.io/jsx/) to describe their relationship to one another. However, you may also use an array of plain [route](/docs/Glossary.md#route) objects if you prefer to avoid using JSX.
 
+The `<Redirect>` configuration helper is not available when using plain routes, so you have to set up the redirect using the `onEnter` hook. 
+
 The route config we've discussed up to this point could also be specified like this:
 
 ```js
-const routeConfig = [
+const routes = [
   { path: '/',
     component: App,
     indexRoute: { component: Dashboard },
@@ -203,18 +205,5 @@ const routeConfig = [
   }
 ]
 
-render(<Router routes={routeConfig} />, document.body)
-```
-
-### Redirect using plain routes configuration
-
-```js
-const routes = [{
-  path: '/',
-  component: Home,
-  onEnter: (nextState, replace) => replace('/about')
-}, {
-  path: '/about',
-  component: About
-}]
+render(<Router routes={routes} />, document.body)
 ```