docs: finish essentials

Author: yyx990803

docs/en/SUMMARY.md

@@ -8,12 +8,12 @@
   - [Getting Started](essentials/getting-started.md)
   - [Dynamic Route Matching](essentials/matching.md)
   - [Nested Routes](essentials/nested-routes.md)
-  - [Redirect and Alias](essentials/redirect-and-alias.md)
   - [Programmatic Navigation](essentials/navigation.md)
+  - [Named Routes](essentials/named-routes.md)
+  - [Named Views](essentials/named-views.md)
+  - [Redirect and Alias](essentials/redirect-and-alias.md)
   - [Server Config for History Mode](essentials/server.md)
 - Advanced
-  - [Named Routes](advanced/named-routes.md)
-  - [Named Views](advanced/named-views.md)
   - [Navigation Guards](advanced/navigation-guards.md)
   - [Animations](advanced/animations.md)
   - [Data Fetching](advanced/data-fetching.md)

docs/en/advanced/named-routes.md renamed to docs/en/essentials/named-routes.md

@@ -1,15 +1,12 @@
 # Named Routes
 
-Sometimes it is more convenient to identify a route with a name, especially when
-performing navigations. You can give a route a name in the `routes` options
-while creating the Router instance:
+Sometimes it is more convenient to identify a route with a name, especially when linking to a route or performing navigations. You can give a route a name in the `routes` options while creating the Router instance:
 
 ``` js
 const router = new VueRouter({
   routes: [
-    // Foo is rendered when /foo is matched
     {
-      path: '/user/:userId',
+      path: '/user/:id',
       name: 'user',
       component: User
     }
@@ -31,3 +28,5 @@ router.push({ name: 'user', params: { userId: 123 }})
 ```
 
 In both cases, the router will navigate to the path `/user/123`.
+
+Full example [here](https://github.com/vuejs/vue-router/blob/next/examples/named-routes/app.js).

docs/en/advanced/named-views.md renamed to docs/en/essentials/named-views.md

@@ -1,18 +1,14 @@
 # Named Views
 
-Sometimes you need to show multiples views at the same time instead of nesting
-them. This is where named views came in handy. Instead of having one single
-outlet in your view, you can have multiple and give each of them a name. A
-`router-view` without a name will be given `default` as its name.
+Sometimes you need to display multiples views at the same time instead of nesting them, e.g. creating a layout with a `sidebar` view and a `main` view. This is where named views came in handy. Instead of having one single outlet in your view, you can have multiple and give each of them a name. A `router-view` without a name will be given `default` as its name.
 
 ``` html
 <router-view class="view one"></router-view>
 <router-view class="view two" name="a"></router-view>
 <router-view class="view three" name="b"></router-view>
 ```
 
-A view is rendered by using a component, therefore multiple views require
-multiple components for the same route. Make sure to use the `components` (with
+A view is rendered by using a component, therefore multiple views require multiple components for the same route. Make sure to use the `components` (with
 an s) option:
 
 ``` js

docs/en/essentials/navigation.md

@@ -1,15 +1,19 @@
 # Programmatic Navigation
 
-Aside from using `<router-link>` to create anchor tags for declarative navigation, we can do this programmatically using vue-router's APIs.
+Aside from using `<router-link>` to create anchor tags for declarative navigation, we can do this programmatically using the router's instance methods.
 
-#### router.push
-It pushes a new entry to the history record. This is the method called internally when you click a `<router-link>`, so clicking `<router-link :to="...">` is the equivalent of calling `router.push(...)`. 
+#### `router.push(location)`
+
+To navigate to a different URL, use `router.push`. This method pushes a new entry into the history stack, so when the user clicks the browser back button they will be taken to the previous URL.
+
+This is the method called internally when you click a `<router-link>`, so clicking `<router-link :to="...">` is the equivalent of calling `router.push(...)`.
 
 | Declarative | Programmatic |
 |-------------|--------------|
 | `<router-link :to="...">` | `router.push(...)` |
 
-Examples: 
+The argument can be a string path, or a location descriptor object. Examples:
+
 ``` js
 // literal string
 router.push('home')
@@ -20,20 +24,22 @@ router.push({ path: 'home' })
 // named route
 router.push({ name: 'user', params: { userId: 123 }})
 
-// with query, resulting in /register?plan=private 
+// with query, resulting in /register?plan=private
 router.push({ path: 'register', query: { plan: 'private' }})
 ```
 
-#### router.replace
-It acts like `router.go`, the only difference is that it navigates without creating a new history record, as its name suggests - it replaces current history record.
+#### `router.replace(location)`
+
+It acts like `router.go`, the only difference is that it navigates without pushing a new history entry, as its name suggests - it replaces the current entry.
 
 | Declarative | Programmatic |
 |-------------|--------------|
 | `<router-link :to="..." replace>` | `router.replace(...)` |
 
 
-#### router.go
-It takes a single integer as parameter that indicates by how many history records to go forwards or go backwards. In router's `history` and `abstract` mode, `router.go` is actually an alias to `window.history.go`, so you can read more about it [here](https://developer.mozilla.org/en-US/docs/Web/API/History).
+#### `router.go(n)`
+
+This method takes a single integer as parameter that indicates by how many steps to go forwards or go backwards in the history stack, similar to `window.history.go(n)`.
 
 Examples
 
@@ -52,18 +58,10 @@ router.go(-100)
 router.go(100)
 ```
 
-
 #### History Manipulation
 
 You may have noticed that `router.push`, `router.replace` and `router.go` are counterparts of [`window.history.pushState`, `window.history.replaceState` and `window.history.go`](https://developer.mozilla.org/en-US/docs/Web/API/History), and they do imitate the `window.history` APIs.
 
 Therefore, if you are already familiar with [Browser History APIs](https://developer.mozilla.org/en-US/docs/Web/API/History_API), manipulating history will be super easy with vue-router.
 
-It is worth mentioning that vue-router APIs (`push`, `replace`, `go`) works consistently under all router modes (`history`, `hash` and `abstract`). Below is a table to give you a quick glance at how vue-router achieves it.
-
-| Router API     | Called under the hood |                       |                    |
-|----------------|-----------------------|-----------------------|--------------------|
-|                | `history` mode        | `hash` mode           | `abstract` mode    |
-| router.push    | history.pushState     | location.hash = ...   | own implementation |
-| router.replace | history.replaceState  | location.replace      | own implementation |
-| router.go      | history.go            | history.go            | own implementation | 
+It is worth mentioning that vue-router navigation methods (`push`, `replace`, `go`) work consistently in all router modes (`history`, `hash` and `abstract`).

docs/en/essentials/nested-routes.md

@@ -74,6 +74,8 @@ const router = new VueRouter({
 })
 ```
 
+**Note that nested paths that start with `/` will be treated as a root path. This allows you to leverage the component nesting without having to use a nested URL.**
+
 As you can see the `children` option is just another Array of route configuration objects like `routes` itself. Therefore, you can keep nesting views as much as you need.
 
 At this point, with the above configuration, when you visit `/user/foo`, nothing will be rendered inside `User`'s outlet, because no sub route is matched. Maybe you do want to render something there. In such case you can provide an empty subroute path:

docs/en/essentials/redirect-and-alias.md

@@ -0,0 +1,58 @@
+# Redirect and Alias
+
+### Redirect
+
+Redirecting is also done in the `routes` configuration. To redirect from `/a` to `/b`:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/a', redirect: '/b' }
+  ]
+})
+```
+
+The redirect can also be targeting a named route:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/a', redirect: { name: 'foo' }}
+  ]
+})
+```
+
+Or even use a function for dynamic redirecting:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/a', redirect: to => {
+      // the function receives the target route as the argument
+      // return redirect path/location here.
+    }}
+  ]
+})
+```
+
+For other advanced usage, checkout the [example](https://github.com/vuejs/vue-router/blob/next/examples/redirect/app.js).
+
+### Alias
+
+A redirect means when the user visits `/a`, and URL will be replaced by `/b`, and then matched as `/b`. But what is an alias?
+
+**An alias of `/a` as `/b` means when the user visits `/b`, the URL remains `/b`, but it will be matched as if the user is visiting `/a`.**
+
+The above can be expressed in the route configuration as:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/a', component: A, alias: '/b' }
+  ]
+})
+```
+
+An alias gives you the freedom to map a UI structure to an arbitrary URL, instead of being constrained by the configuration's nesting structure.
+
+For advanced usage, checkout the [example](https://github.com/vuejs/vue-router/blob/next/examples/route-alias/app.js).

docs/en/essentials/server.md

@@ -1,15 +1,14 @@
-# Server Configuration for history mode
+# Server Configuration for History Mode
 
-The Router's history mode enables the use of the HTML5 pushstate adding the ability for your app to change the URL of your site without refreshing the page, and without the use of the hashbang in the URL. Using this mode however requires some pre-configuration of your server otherwise when a user visits deep linked content they'll be served a 404 Not Found. Below you can find configuration samples for several server softwares.
+The default mode for `vue-router` is hash mode - it uses the URL hash to simulate a full URL so that the page won't be reloaded when the URL changes.
 
-There are a few caveats to this, in that your server will no longer report 404 errors as all paths will serve up your index.html file. To get around this issue you should implement a catch-all route and display a 404 page within your Vue app. See the [Caveats](#caveats) section for more information.
+To get rid of the ugly hash, we can use the HTML5 `history.pushState` API to achieve URL navigation without page reload. But for this mode to work properly, you need to configure your server properly.
 
- - [Server Configurations](#server-configurations)
-   - [Apache](#apache)
-   - [nginx](#nginx)
- - [Caveats](#caveats)
+Because when using history mode, the URL will look like a normal url, e.g. `http://yoursite.com/user/id`. Since our app is a single page client side app, without proper server configuration the users will get a 404 if they visit that URL directly.
 
-## Server Configurations
+Therefore you need to add a catch-all fallback route to your server: if the URL doesn't match any static assets, it should serve the same `index.html` page that your app lives in.
+
+## Example Server Configurations
 
 #### Apache
 
@@ -32,15 +31,21 @@ location / {
 }
 ```
 
+#### Node.js (Express)
+
+https://github.com/bripkens/connect-history-api-fallback
+
 ## Caveats
 
-To get around the issue that the server will no longer serve 404 errors you should implement a catch-all route within your Vue app to show a 404 page.
+There is a caveats to this, because that your server will no longer report 404 errors as all paths will serve up your `index.html` file. To get around the issue, you should implement a catch-all route within your Vue app to show a 404 page:
 
 ```javascript
-new VueRouter({
+const router = new VueRouter({
   mode: 'history',
   routes: [
     { path: '*', component: NotFoundComponent }
   ]
 })
 ```
+
+Alternatively, if you are using a Node.js server, you can implement the fallback by using the router on the server side to match the incoming URL, and respond with 404 if no route is matched.