Improve Initial Docs Experience

packages/react-router-dom/docs/guides/quick-start.md

@@ -21,79 +21,96 @@ yarn add react-router-dom
 npm install react-router-dom
 ```
 
-Now you can copy/paste any of the examples into `src/App.js`. Here's the
-basic one:
+## Examples
+
+Copy/paste either of the examples (below) into your `src/App.js`. 
+
+### Example: Basic Routing
+
+In this example we have 3 'Page' Components handled by the `<Router>`. 
+
+Note: Instead of `<a href="/">` we use `<Link to="/">`.
 
 ```jsx
 import React from "react";
 import { BrowserRouter as Router, Route, Link } from "react-router-dom";
+const Home = () => <h2>Home</h2>;
+const About = () => <h2>About</h2>;
+const Users = () => <h2>Users</h2>;
 
-const Home = () => (
-  <div>
-    <h2>Home</h2>
-  </div>
-);
+const AppRouter = () => (
+  <Router>
+    <div>
+      <nav>
+        <ul>
+          <li><Link to="/">Home</Link></li>
+          <li><Link to="/about/">About</Link></li>
+          <li><Link to="/users/">Users</Link></li>
+        </ul>
+      </nav>
+
+      <Route path="/" exact component={Home} />
+      <Route path="/about/" component={About} />
+      <Route path="/users/" component={Users} />
 
-const About = () => (
-  <div>
-    <h2>About</h2>
-  </div>
+    </div>
+  </Router>
 );
 
-const Topic = ({ match }) => (
-  <div>
-    <h3>{match.params.topicId}</h3>
-  </div>
+export default AppRouter;
+```
+
+### Example: Nested Routing
+
+This example shows how nested routing works. The route `/topics` loads the `Topics` component, which resolves any further `<Route>`'s conditionally on the paths `:id`.
+
+```jsx
+import React from "react";
+import { BrowserRouter as Router, Route, Link } from "react-router-dom";
+
+const AppRouter = () => (
+  <Router>
+    <div>
+      <Header />
+
+      <Route exact path="/" component={Home} />
+      <Route path="/about" component={About} />
+      <Route path="/topics" component={Topics} />
+
+    </div>
+  </Router>
 );
 
+const Home = () => <h2>Home</h2>;
+const About = () => <h2>About</h2>;
+const Topic = ({ match }) => <h3>Requested Param: {match.params.id}</h3>;
 const Topics = ({ match }) => (
   <div>
     <h2>Topics</h2>
+
     <ul>
-      <li>
-        <Link to={`${match.url}/rendering`}>Rendering with React</Link>
-      </li>
-      <li>
-        <Link to={`${match.url}/components`}>Components</Link>
-      </li>
-      <li>
-        <Link to={`${match.url}/props-v-state`}>Props v. State</Link>
-      </li>
+      <li><Link to={`${match.url}/components`}>Components</Link></li>
+      <li><Link to={`${match.url}/props-v-state`}>Props v. State</Link></li>
     </ul>
 
-    <Route path={`${match.path}/:topicId`} component={Topic} />
+    <Route path={`${match.path}/:id`} component={Topic} />
     <Route
       exact
       path={match.path}
-      render={() => <h3>Please select a topic.</h3>}
+      render={() => <h3>Please select a topic.</h3>}      
     />
+
   </div>
 );
-
-const BasicExample = () => (
-  <Router>
-    <div>
-      <ul>
-        <li>
-          <Link to="/">Home</Link>
-        </li>
-        <li>
-          <Link to="/about">About</Link>
-        </li>
-        <li>
-          <Link to="/topics">Topics</Link>
-        </li>
-      </ul>
-
-      <hr />
-
-      <Route exact path="/" component={Home} />
-      <Route path="/about" component={About} />
-      <Route path="/topics" component={Topics} />
-    </div>
-  </Router>
+const Header = () => (
+  <ul>
+    <li><Link to="/">Home</Link></li>
+    <li><Link to="/about">About</Link></li>
+    <li><Link to="/topics">Topics</Link></li>
+  </ul>
 );
-export default BasicExample;
+
+export default AppRouter;
 ```
 
 Now you're ready to tinker. Happy routing!

packages/react-router/docs/guides/philosophy.md

@@ -7,6 +7,7 @@ This guide's purpose is to explain the mental model to have when using React Rou
 If you've used Rails, Express, Ember, Angular etc. you've used static routing. In these frameworks, you declare your routes as part of your app's initialization before any rendering takes place. React Router pre-v4 was also static (mostly). Let's take a look at how to configure routes in express:
 
 ```js
+// Express Style routing:
 app.get("/", handleIndex);
 app.get("/invoices", handleInvoices);
 app.get("/invoices/:id", handleInvoice);
@@ -18,6 +19,7 @@ app.listen();
 Note how the routes are declared before the app listens. The client side routers we've used are similar. In Angular you declare your routes up front and then import them to the top-level `AppModule` before rendering:
 
 ```js
+// Angular Style routing:
 const appRoutes: Routes = [
   {
     path: "crisis-center",
@@ -54,6 +56,7 @@ imports into the application for you. Again, this happens before
 your app renders.
 
 ```js
+// Ember Style Router:
 Router.map(function() {
   this.route("about");
   this.route("contact");

website/modules/docs/Web.js

@@ -19,12 +19,12 @@ export default {
   ],
 
   guides: [
-    require("../../../packages/react-router/docs/guides/philosophy.md"),
-    require("../../../packages/react-router-dom/docs/guides/basic-components.md"),
     require("../../../packages/react-router-dom/docs/guides/quick-start.md"),
+    require("../../../packages/react-router-dom/docs/guides/basic-components.md"),
     require("../../../packages/react-router-dom/docs/guides/server-rendering.md"),
     require("../../../packages/react-router-dom/docs/guides/code-splitting.md"),
     require("../../../packages/react-router-dom/docs/guides/scroll-restoration.md"),
+    require("../../../packages/react-router/docs/guides/philosophy.md"),
     require("../../../packages/react-router/docs/guides/testing.md?web"),
     require("../../../packages/react-router/docs/guides/redux.md"),
     require("../../../packages/react-router/docs/guides/static-routes.md"),