more docs

Author: yyx990803

docs/README.md

@@ -1,10 +1,26 @@
 # Introduction
 
+### What is `vue-loader`?
+
+`vue-loader` is a loader for Webpack that can transform Vue components written in the following format into a plain JavaScript module:
+
+![screenshot](http://blog.evanyou.me/images/vue-component.png)
+
+There are many cool features provided by `vue-loader`:
+
+- ES2015 enabled by default;
+- Allows using other Webpack loaders for each part of a Vue component, for example SASS for `<style>` and Jade for `<template>`;
+- Treat static assets referenced in `<style>` and `<template>` as module dependencies and handle them with Webpack loaders;
+- Can simulate scoped CSS for each component;
+- Supports component hot-reloading during development.
+
+In a nutshell, the combination of Webpack and `vue-loader` gives you a modern, flexible and extremely powerful front-end workflow for authoring Vue.js applications.
+
 ### What is Webpack?
 
-Before we talk about `vue-loader`, let's first introduce [Webpack](http://webpack.github.io/). If you are already familiar with Webpack, feel free to skip the following explanation. But for those of you who are new to Webpack, here's a quick intro:
+If you are already familiar with Webpack, feel free to skip the following explanation. But for those of you who are new to Webpack, here's a quick intro:
 
-Webpack is a module bundler. It takes a bunch of files, treating each as a module, figuring out the dependencies between them, and bundle them into static assets that are ready for deployment.
+[Webpack](http://webpack.github.io/) is a module bundler. It takes a bunch of files, treating each as a module, figuring out the dependencies between them, and bundle them into static assets that are ready for deployment.
 
 ![webpack](http://webpack.github.io/assets/what-is-webpack.png)
 
@@ -19,19 +35,3 @@ But Webpack can do more than that. With "loaders", we can teach Webpack to trans
 - Process an image file referenced in HTML or CSS, moved it to the desired destination based on the path configurations, and naming it using its md5 hash.
 
 Webpack is so powerful that when you understand how it works, it can dramatically improve your front-end workflow. Its primary drawback is verbose and complex configuration; but with this guide you should be able to find solutions for most common issues when using Webpack with Vue.js and `vue-loader`.
-
-### What is `vue-loader`?
-
-`vue-loader` is a loader for Webpack that can transform Vue components written in the following format into a plain JavaScript module:
-
-![screenshot](http://blog.evanyou.me/images/vue-component.png)
-
-There are many cool features provided by `vue-loader`:
-
-- ES2015 enabled by default;
-- Allows using other Webpack loaders for each part of a Vue component, for example SASS for `<style>` and Jade for `<template>`;
-- Treat static assets referenced in `<style>` and `<template>` as module dependencies and handle them with Webpack loaders;
-- Can simulate scoped CSS for each component;
-- Supports component hot-reloading during development.
-
-In a nutshell, the combination of Webpack and `vue-loader` gives you a modern, flexible and extremely powerful front-end workflow for authoring Vue.js applications.

docs/SUMMARY.md

@@ -4,7 +4,7 @@
 - Configurations
   - [Inline Loaders](configurations/inline-loaders.md)
   - [Asset URL Handling](configurations/asset-url.md)
-  - [Babel and ES2015](configurations/es2015.md)
+  - [ES2015 and Babel](configurations/es2015.md)
   - [PostCSS and Autoprefixer](configurations/postcss.md)
   - [Advanced Loader Configuration](configurations/advanced.md)
   - [Extracting CSS File](configurations/extract-css.md)
@@ -14,3 +14,4 @@
 - Workflow
   - [Linting](workflow/linting.md)
   - [Testing](workflow/testing.md)
+  - [Production Build](workflow/production.md)

docs/configurations/es2015.md

@@ -1,13 +1,33 @@
-# Configuring JavaScript in Vue Components
+# ES2015 and Babel Configuration
 
-### ES2015 by Default
+`vue-loader` ships with ES2015 (aka ES6) enabled by default in `<script>` tags. All scripts inside Vue components are compiled with [Babel](https://babeljs.io/) using `babel-loader`. If you haven't picked up the new language features yet, you definitely should. Some good learning resources:
 
-`vue-loader` ships with ES2015 enabled by default in `<script>` tags. All scripts inside Vue components are compiled with [Babel](https://babeljs.io/) using `babel-loader`.
+- [Babel - Learn ES2015](https://babeljs.io/docs/learn-es2015/)
+- [ES6 Features](https://github.com/lukehoban/es6features)
+- [Exploring ES6 (book)](https://leanpub.com/exploring-es6)
 
-> **Compatibility Note**: `vue-loader` 7.0+ uses Babel 6. If you need to use Babel 5 for transpiling your code, use vue-loader 6.x.
+Here's a typical pattern you will see when importing other Vue components:
+
+``` html
+<script>
+import ComponentA from './ComponentA.vue'
+import ComponentB from './ComponentB.vue'
+
+export default {
+  components: {
+    ComponentA,
+    ComponentB
+  }
+}
+</script>
+```
+
+We are using ES2015's Object literal shorthand here to define the child components. `{ ComponentA }` is simply shorthand for `{ ComponentA: ComponentA }`. Vue will automatically convert the key to `component-a`, so you can use the imported component in the template as `<component-a>`.
 
 ### Using Custom Babel Configuration
 
+> **Compatibility Note**: `vue-loader` 7.0+ uses Babel 6. If you need to use Babel 5 for transpiling your code, use vue-loader 6.x.
+
 The default Babel options used for scripts inside Vue components are:
 
 ``` json

docs/features/hot-reload.md

@@ -0,0 +1,40 @@
+# Hot Reload
+
+"Hot Reload" is not simply reloading the page when you edit a file. With hot reload enabled, when you edit a `*.vue` file, all instances of that component will be swapped in **without reloading the page**. It even preserves the current state of your app and these swapped components! This dramatically improves the development experience when you are tweaking the templates or styling of your components.
+
+![hot-reload](http://blog.evanyou.me/images/vue-hot.gif)
+
+### Enabling Hot Reload
+
+The easiest setup for enabling hot reload is what we outlined in the [basic tutorial](../start/tutorial.md):
+
+``` js
+// package.json
+"scripts": {
+  "dev": "webpack-dev-server --inline --hot"
+}
+```
+
+This is assuming that you are serving the same `index.html` from the root of your project. By default, Webpack dev server uses the current working directory as its content base and serves all static files in the directory.
+
+Run `npm run dev` and the static app will be served at `http://localhost:8080`.
+
+### Hot Reload Notes
+
+- When a component is hot-reloaded, its current state is preserved. However, the component itself is destroyed and recreated, so all of its lifecycle hooks will be called accordingly. Make sure to properly teardown any side effects in your lifecycle hooks.
+
+- Private state for child components of a hot-reloaded component is not guaranteed to be preserved across reloads.
+
+- A root Vue instance or a manually mounted instance cannot be hot-reloaded. It will always force a full reload.
+
+### Configuration Tips
+
+- You can use the `--port` option to serve at a different port.
+
+- If your file structure is different, you will have to configure `output.publicPath` in your Webpack config and the `--content-base` option of your webpack-dev-server command accordingly.
+
+- If you are using the HTML5 history API (for example with `vue-router`), you will also want to add the `--history-api-fallback` option.
+
+- Consult the [Webpack dev server documentation](https://webpack.github.io/docs/webpack-dev-server.html) for advanced topics such as combining the dev server with another backend server.
+
+- Finally, if you have an existing [Express](http://expressjs.com/en/index.html) based Node.js backend, you can just add the [Webpack dev middleware](https://webpack.github.io/docs/webpack-dev-middleware.html) to serve your webpack bundle.

docs/features/scoped-css.md

@@ -0,0 +1,49 @@
+# Scoped CSS
+
+When a `<style>` tag has the `scoped` attribute, its CSS will apply to elements of the current component only. This is similar to the style encapsulation found in Shadow DOM. It comes with some caveats, but doesn't require any polyfills. It is achieved by using PostCSS to transform the following:
+
+``` html
+<style scoped>
+.example {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example">hi</div>
+</template>
+```
+
+Into the following:
+
+``` html
+<style>
+.example[_v-f3f3eg9] {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example" _v-f3f3eg9>hi</div>
+</template>
+```
+
+#### Notes
+
+1. You can include both scoped and non-scoped styles in the same component:
+
+  ``` html
+  <style>
+  /* global styles */
+  </style>
+
+  <style scoped>
+  /* local styles */
+  </style>
+  ```
+
+2. A child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS.
+
+3. Partials are not affected by scoped styles.
+
+4. **Be careful with descendant selectors in recursive components!** For a CSS rule with the selector `.a .b`, if the element that matches `.a` contains a recursive child component, then all `.b` in that child component will be matched by the rule.

docs/start/spec.md

@@ -26,19 +26,27 @@ export default {
 
 `vue-loader` will parse the file, extract each language block, pipe them through other loaders if necessary, and finally assemble them back into a CommonJS module whose `module.exports` is a Vue.js component options object.
 
-`vue-loader` supports using non-default languages, such as CSS pre-processors and compile-to-HTML template languages, by specifying the `lang` attribute for a language block. The details are discussed in [Inline Loaders](../configurations/inline-loaders.md).
+`vue-loader` supports using non-default languages, such as CSS pre-processors and compile-to-HTML template languages, by specifying the `lang` attribute for a language block. For example, you can use SASS for the style of your component like this:
 
-Some more details on the language blocks:
+``` html
+<style lang="sass">
+  /* write SASS! */
+</style>
+```
+
+More details can be found in [Inline Loaders](../configurations/inline-loaders.md).
+
+### Language Blocks
 
-### `<template>`
+#### `<template>`
 
 - Default language: `html`.
 
 - Each `*.vue` file can contain at most one `<template>` block at a time.
 
 - Contents will be extracted as a string and used as the `template` option for the compiled Vue component. 
 
-### `<script>`
+#### `<script>`
 
 - Default language: `js` (ES2015 is supported by default via Babel).
 
@@ -48,7 +56,7 @@ Some more details on the language blocks:
 
 - The script must export a Vue.js component options object. Exporting an extended constructor created by `Vue.extend()` is also supported, but a plain object is preferred.
 
-### `<style>`
+#### `<style>`
 
 - Defalt Language: `css`.