docs wip

Author: yyx990803

Diff for: .gitignore

@@ -1,3 +1,4 @@
-/node_modules
-/npm-debug.log
+node_modules
+npm-debug.log
 test/output
+docs/_book

Diff for: README.md

@@ -4,28 +4,7 @@
 
 It allows you to write your components in this format:
 
-``` html
-<!-- app.vue -->
-<template>
-  <h1 class="red">{{msg}}</h1>
-</template>
-
-<script>
-export default {
-  data () {
-    return {
-      msg: 'Hello world!'
-    }
-  }
-}
-</script>
-
-<style>
-.red {
-  color: #f00;
-}
-</style>
-```
+![screenshot](http://blog.evanyou.me/images/vue-component.png)
 
 ## Table of Contents
 
@@ -39,6 +18,9 @@ export default {
 - [Asset URL Handling](#asset-url-handling)
 - [Scoped CSS](#scoped-css)
 - [Hot Reload](#hot-reload)
+- [Syntax Highlighting](#syntax-highlighting)
+- [Linting](#linting)
+- [Testing](#testing)
 - [Advanced Loader Configuration](#advanced-loader-configuration)
 - [Example Project](https://github.com/vuejs/vue-loader-example)
 
@@ -172,11 +154,12 @@ For template pre-processors, you should install `template-html-loader` plus the
 
 ## Src Imports
 
-If you want, you can separate your template and styles into separate files and import them using the `src` attribute:
+If you want, you can separate your templates, styles or scripts into separate files and import them using the `src` attribute:
 
 ``` html
 <template src="./template.html"></template>
 <style src="./style.css"></style>
+<script src="./script.js"></script>
 ```
 
 Beware that `src` imports follow similar rules to `require()` calls, which means for relative paths you need to start with `./`, and you can import resources from installed NPM packages, e.g. `<style src="todomvc-app-css/index.css">`.

Diff for: docs/README.md

@@ -0,0 +1,37 @@
+# Introduction
+
+### 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:
+
+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/assets/what-is-webpack.png)
+
+For a basic example, imagine we have a bunch of CommonJS modules. They cannot run directly inside the browser, so we need to "bundle" them into a single file that can be included via a `<script>` tag. Webpack can follow the dependencies of the `require()` calls and do that for us.
+
+But Webpack can do more than that. With "loaders", we can teach Webpack to transform all types of files in anyway we want before outputting the final bundle. Some examples include:
+
+- Transpile ES2015, CoffeeScript or TypeScript modules into plain ES5 CommonJS modules;
+- Optionally you can pipe the source code through a linter before doing the compilation;
+- Transpile Jade templates into plain HTML and inline it as a JavaScript string;
+- Transpile SASS files into plain CSS, then convert it into a JavaScript snippet that insert the resulting CSS as a `<style>` tag;
+- 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.

Diff for: docs/SUMMARY.md

@@ -0,0 +1,16 @@
+- Getting Started
+  - [Vue Component Spec](start/spec.md)
+  - [Basic Tutorial](start/tutorial.md)
+- Configurations
+  - [Inline Loaders](configurations/inline-loaders.md)
+  - [Asset URL Handling](configurations/asset-url.md)
+  - [Babel and ES2015](configurations/es2015.md)
+  - [PostCSS and Autoprefixer](configurations/postcss.md)
+  - [Advanced Loader Configuration](configurations/advanced.md)
+  - [Extracting CSS File](configurations/extract-css.md)
+- Features
+  - [Scoped CSS](features/scoped-css.md)
+  - [Hot Reload](features/hot-reload.md)
+- Workflow
+  - [Linting](workflow/linting.md)
+  - [Testing](workflow/testing.md)

Diff for: docs/assets/CNAME

@@ -0,0 +1 @@
+vue-loader.vuejs.org

Diff for: docs/assets/circle.yml

@@ -0,0 +1,4 @@
+general:
+  branches:
+    ignore:
+      - gh-pages

Diff for: docs/book.json

@@ -0,0 +1,19 @@
+{
+  "gitbook": "2.x.x",
+  "plugins": ["edit-link", "github"],
+  "pluginsConfig": {
+    "edit-link": {
+      "base": "https://github.com/vuejs/vue-loader/tree/master/docs",
+      "label": "Edit This Page"
+    },
+    "github": {
+      "url": "https://github.com/vuejs/vue-loader/"
+    }
+  },
+  "links": {
+    "sharing": {
+      "facebook": false,
+      "twitter": false
+    }
+  }
+}

Diff for: docs/configurations/advanced.md

@@ -0,0 +1,33 @@
+# Advanced Loader Configuration
+
+Sometimes you may want to apply a custom loader string to a language instead of letting `vue-loader` infer it. Or you may simply want to overwrite the built-in loader configuration for the default languages. To do that, add a `vue` block in your Webpack config file, and specify the `loaders` option.
+
+Example:
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other options...
+  module: {
+    loaders: [
+      {
+        test: /\.vue$/,
+        loader: 'vue'
+      }
+    ]
+  },
+  // vue-loader configurations
+  vue: {
+    // ... other vue options
+    loaders: {
+      // load all <script> without "lang" attribute with coffee-loader
+      js: 'coffee',
+      // load <template> directly as HTML string, without piping it
+      // through vue-html-loader first
+      html: 'raw'
+    }
+  }
+}
+```
+
+A more practical usage of the advanced loader configuration is [extracting CSS inside components into a single file](./extract-css.md).

Diff for: docs/configurations/asset-url.md

@@ -0,0 +1,38 @@
+# Asset URL Handling
+
+By default, `vue-loader` automatically processes your style and template files with [css-loader](https://github.com/webpack/css-loader) and [vue-html-loader](https://github.com/vuejs/vue-html-loader) (which is just a Vue-specific fork of [html-loader](https://github.com/webpack/html-loader)). What this means is that all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
+
+For example, `url(image.png)` will be translated into `require('./image.png')`. Because `.png` is not JavaScript, you will need to configure Webpack to use [file-loader](https://github.com/webpack/file-loader) or [url-loader](https://github.com/webpack/url-loader) to handle them. This may feel cumbersome, but it gives us some very powerful benefits by managing static assets this way:
+
+1. `file-loader` allows you to designate where to copy and place the asset file, and how to name it using version hashes. The best part though, is that you can use relative URLs based on the folder structure of your source files, and Webpack will auto-rewrite them into different URLs in the bundled files based on the configuration.
+
+2. `url-loader` allows you to conditionally inline a file as base-64 data URL if they are smaller than a given threshold. This can reduce the amount of HTTP requests for trivial files. If the file is larger than the threshold, it automatically fallbacks to `file-loader`.
+
+Here's an example Webpack config that handles `.png`, `jpg` and `.gif` files, and inlining any file smaller than 10kb as base64 data URL:
+
+``` bash
+npm install url-loader file-loader --save-dev
+```
+
+``` js
+// webpack.config.js
+module.exports = {
+  // ... other options
+  module: {
+    loaders: [
+      // ... other loaders
+      {
+        test: /\.(png|jpg|gif)$/,
+        loader: 'url',
+        query: {
+          // limit for base64 inlining in bytes
+          limit: 10000,
+          // custom naming format if file is larger than
+          // the threshold
+          name: '[name].[ext]?[hash]'
+        }
+      }
+    ]
+  }
+}
+```

Diff for: docs/configurations/es2015.md

@@ -0,0 +1,70 @@
+# Configuring JavaScript in Vue Components
+
+### ES2015 by Default
+
+`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`.
+
+> **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.
+
+### Using Custom Babel Configuration
+
+The default Babel options used for scripts inside Vue components are:
+
+``` json
+{
+  "presets": ["es2015"],
+  "plugins": ["transform-runtime"]
+}
+```
+
+If you want to use custom presets or plugins, for example enable stage-0 language features, install the preset/plugin and then add a `babel` field in your Webpack config:
+
+``` bash
+npm install babel-preset-stage-0 --save-dev
+```
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other configs...
+  babel: {
+    // enable stage 0 babel transforms.
+    presets: ['es2015', 'stage-0'],
+    plugins: ['transform-runtime']
+  }
+}
+```
+
+### Compiling `.js` Files with Babel
+
+Since we are already using Babel, most likely you'll want to compile your normal `.js` files too! Here's how to do it in your Webpack config:
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other options ...
+  module: {
+    loaders: [
+      {
+        // use vue-loader for *.vue files
+        test: /\.vue$/,
+        loader: 'vue'
+      },
+      {
+        // use babel-loader for *.js files
+        test: /\.js$/,
+        loader: 'babel',
+        // important: exclude files in node_modules
+        // otherwise it's going to be really slow!
+        exclude: /node_modules/
+      }
+    ]
+  },
+  // if you are using babel-loader directly then
+  // the babel config block becomes required.
+  babel: {
+    presets: ['es2015'],
+    plugins: ['transform-runtime']
+  }
+}
+```

Diff for: docs/configurations/extract-css.md

@@ -0,0 +1,34 @@
+# Extracting CSS into a Single File
+
+Example config to extract all the processed CSS in all Vue components into a single CSS file:
+
+``` bash
+npm install extract-text-webpack-plugin --save-dev
+```
+
+``` js
+// webpack.config.js
+var ExtractTextPlugin = require("extract-text-webpack-plugin");
+
+module.exports = {
+  // other options...
+  module: {
+    loaders: [
+      {
+        test: /\.vue$/,
+        loader: 'vue'
+      },
+    ]
+  },
+  vue: {
+    loaders: {
+      css: ExtractTextPlugin.extract("css"),
+      // you can also include <style lang="less"> or other langauges
+      less: ExtractTextPlugin.extract("css!less")
+    }
+  },
+  plugins: [
+    new ExtractTextPlugin("style.css")
+  ]
+}
+```

Diff for: docs/configurations/inline-loaders.md

@@ -0,0 +1,62 @@
+# Inline Loaders
+
+`vue-loader` allows you to use other Webpack loaders to process a part of a Vue component. It will automatically infer the proper loaders to use from the `lang` attribute of a language block.
+
+### CSS
+
+For example, let's compile our `<style>` tag with SASS:
+
+``` bash
+npm install sass-loader --save-dev
+```
+
+``` html
+<style lang="sass">
+  /* write sass here */
+</style>
+```
+
+Under the hood, the text content inside the `<style>` tag will be first compiled by `sass-loader` before being passed on for further processing.
+
+### JavaScript
+
+All JavaScript inside Vue components are processed by `babel-loader` by default. But you can of course change it:
+
+``` bash
+npm install coffee-loader --save-dev
+```
+
+``` html
+<script lang="coffee">
+  # Write coffeesciprt!
+</script>
+```
+
+We will talk more about Babel/ES2015 configurations in another section.
+
+### Templates
+
+Processing templates is a little different, because most Webpack template loaders such as `jade-loader` returns a template function instead of compiled HTML string. So instead of using `jade-loader`, we will use `template-html-loader` plus the raw `jade` compiler:
+
+``` bash
+npm install template-html-loader jade --save-dev
+```
+
+``` html
+<template lang="jade">
+div
+  h1 Hello world!
+</template>
+```
+
+### Inline Loader Requests
+
+You can use [Webpack loader requests](https://webpack.github.io/docs/loaders.html#introduction) in the `lang` attribute:
+
+``` html
+<style lang="sass?outputStyle=expanded">
+  /* use sass here with expanded output */
+</style>
+```
+
+However, note this makes your Vue component Webpack-specific and not compatible with Browserify and [vueify](https://github.com/vuejs/vueify). **If you intend to ship your Vue component as a reusable 3rd-party component, avoid using this syntax.**