chore: Various doc recommendations (#222)

* various doc recommendations

* chore: Fix getting started link and remove examples and options from main nav

Author: chrisvfritz

docs/.vuepress/config.js

@@ -17,31 +17,25 @@ module.exports = {
         label: 'English',
         selectText: 'Languages',
         editLinkText: 'Edit this page on GitHub',
-        nav: [{
-            text: 'Guide',
-            link: '/guide/'
-          },
+        nav: [
           {
-            text: 'Options Reference',
-            link: '/options'
+            text: 'Getting Started',
+            link: '/getting-started'
           },
           {
             text: 'Migrating from v2',
             link: '/migrating'
-          },
-          {
-            text: 'Cookbook',
-            link: '/cookbook/'
           }
         ],
         sidebar: [
-          '/',
-          '/guide/',
+          {
+            title: 'Guide',
+            children: ['/', '/getting-started', '/examples']
+          },
           '/options',
-          '/cookbook/',
           '/changelog'
         ]
       }
     }
   }
-}
+}

docs/README.md

@@ -4,20 +4,20 @@
 This is the documentation for Rollup Plugin Vue v4 and above. If you are upgrading from v2 or an earlier version, check out the [Migration Guide](./migrating.md). If you are using an older version, the old docs are [here](https://github.com/vuejs/rollup-plugin-vue/tree/2.2/docs).
 :::
 
-## What is Rollup Plugin Vue?
+## What does Rollup Plugin Vue do?
 
-`rollup-plugin-vue` is a plugin for [rollup](https://rollupjs.org/) that allows you to author Vue components in a format called [Single-File Components (SFCs)](https://vue-loader.vuejs.org/spec.html):
+This is a plugin for [rollup](https://rollupjs.org/) that allows you to author Vue components in a format called [Single-File Components (SFCs)](https://vue-loader.vuejs.org/spec.html). They look like this:
 
 ``` vue
 <template>
-  <div class="example">{{ msg }}</div>
+  <div class="example">{{ message }}</div>
 </template>
 
 <script>
 export default {
   data () {
     return {
-      msg: 'Hello world!'
+      message: 'Hello world!'
     }
   }
 }
@@ -30,11 +30,14 @@ export default {
 </style>
 ```
 
-There are many cool features provided by `rollup-plugin-vue`:
+This plugin also enables:
 
-- Feature parity with [vue-loader](https://vue-loader.vuejs.org)
-- Allows custom blocks in a `.vue` file;
-- Treat static assets referenced in `<style>` and `<template>` as module dependencies;
-- Simulate scoped CSS for each component.
+- scoped CSS
+- custom blocks
+- static assets references within `<style>` and `<template>`
 
-Rollup is a module bundler which makes `rollup-plugin-vue` ideal for packaging Vue plugins and UI component libraries.
+And many other other features, maintaining parity with [Vue Loader](https://vue-loader.vuejs.org).
+
+## Why should I use Rollup over Webpack?
+
+Rollup offers optimizations like tree shaking that make it ideal for building shared libraries. This plugin also prioritizes defaults that are ideal for most Vue plugins and UI component libraries.

docs/cookbook/README.md renamed to docs/examples.md

@@ -1,6 +1,6 @@
-# Cookbook
+# Examples
 
-The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach.
+These examples cover most common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach.
 
 ## Minimal
 
@@ -26,7 +26,7 @@ Source: [cookbook/typescript-simple](https://github.com/vuejs/rollup-plugin-vue/
 
 ## SSR
 
-<<< @/cookbook/ssr/rollup.config.js{2,12-16}
+<<< @/cookbook/ssr/rollup.config.js{10}
 
 Source: [cookbook/ssr](https://github.com/vuejs/rollup-plugin-vue/tree/master/cookbook/ssr)
 

docs/getting-started.md

@@ -0,0 +1,17 @@
+# Getting Started
+
+Add `rollup-plugin-vue` to the `plugins` array in `rollup.config.js`:
+
+``` js
+import vue from 'rollup-plugin-vue'
+
+export default {
+  // ...
+  plugins: [
+    // ...
+    vue(/* options */)
+  ]
+}
+```
+
+That's all you need! You can customize this plugin's behavior by passing it an optional [options object](/options.html).

docs/guide/README.md

@@ -1,21 +1,22 @@
 ---
-sidebar: auto
+sidebarDepth: 2
 ---
-# Options Reference
 
-## include
+# Options
+
+## `include`
 
 - type: `Array<string|RegExp> | string | RegExp`
 - default: `[/\.vue$/i]`
 
-## exclude
+## `exclude`
 
 - type: `Array<string|RegExp> | string | RegExp`
 - default: `[]`
 
 A minimatch pattern or a regular expression or an array of minimatch patterns or regular expressions.
 
-## defaultLang
+## `defaultLang`
 
 - type: `{ [key: string]: string }`
 - default: `{}`
@@ -28,96 +29,96 @@ e.g.: `defaultLang: { script: 'ts' }` would set default `<script>` block languag
 `defaultLang` does not set default language in templates for your editor/IDE.
 :::
 
-## blackListCustomBlocks
+## `blackListCustomBlocks`
 
 - type: `string[]`
 - default: `['*']`
 
 Exclude custom block from final bundle.
 
-## whiteListCustomBlocks
+## `whiteListCustomBlocks`
 
 - type: `string[]`
 - default: `[]`
 
 Include custom block in final bundle.
 
-## css
+## `css`
 
 - type: `boolean`
 - default: `true`
 
 Inject CSS in JavaScript. Setting `css: false` would extract styles in a `.css` file.
 
-## compiler
+## `compiler`
 
 - type: [VueTemplateCompiler](https://github.com/vuejs/component-compiler-utils#parseparseoptions-sfcdescriptor)
 - default: `require('vue-template-compiler')`
 
 Override template parser.
 
-## compilerParseOptions
+## `compilerParseOptions`
 
 - type: [VueTemplateCompilerParseOptions](https://github.com/vuejs/component-compiler-utils#parseparseoptions-sfcdescriptor)
 - default: `undefined`
 
-## sourceRoot
+## `sourceRoot`
 
 - type: string
 - default: `process.cwd()`
 
-## style
+## `style`
 
 `@vue/component-compiler` options to process `<style>` blocks in SFCs.
 
-### style.postcssOptions
+### `style.postcssOptions`
 
 - type: `any`
 - default: `undefined`
 
-### style.postcssPlugins
+### `style.postcssPlugins`
 
 - type: `any[]`
 - default: `undefined`
 
-### style.postcssCleanOptions
+### `style.postcssCleanOptions`
 
 - type: `object`
 - default: `{}`
 
-### style.postcssModulesOptions
+### `style.postcssModulesOptions`
 
 - type: `object`
 - default:
 
   ``` js
-  { 
-    generateScopedName: '[path][local]-[hash:base64:4]' 
+  {
+    generateScopedName: '[path][local]-[hash:base64:4]'
   }
   ```
 
-### style.preprocessOptions
+### `style.preprocessOptions`
 
 - type: `{ [lang: string]: object }`
 - default: `{}`
 
-### style.trim
+### `style.trim`
 
 - type: `boolean`
 - default: `true`
 
-## template
+## `template`
 
 `@vue/component-compiler` options to process `<template>` blocks in SFCs.
 
-### template.compiler
+### `template.compiler`
 
 - type: `VueTemplateCompiler`
 - default: `require('vue-template-compiler')`
 
 Override the default compiler used to compile `<template>` blocks in single file components.
 
-### template.compilerOptions
+### `template.compilerOptions`
 
 - type: `Object`
 - default: `{}`
@@ -126,7 +127,7 @@ Options for the template compiler. When using the default vue-template-compiler,
 
 See [`vue-template-compiler` options reference](https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#options).
 
-### template.transformAssetUrls
+### `template.transformAssetUrls`
 
 - type: `{ [tag: string]: string | Array<string> }`
 - default:
@@ -142,21 +143,21 @@ See [`vue-template-compiler` options reference](https://github.com/vuejs/vue/tre
 
 During template compilation, the compiler can transform certain attributes, such as `src` URLs, into `require` calls, so that the target asset can be handled by webpack. For example, `<img src="./foo.png">` will attempt to locate the file `./foo.png` on your file system and include it as a dependency of your bundle.
 
-### template.isProduction
+### `template.isProduction`
 
 - type: `boolean`
 - default: `process.env.NODE_ENV === 'production' || process.env.BUILD === 'production'`
 
 Force production mode, which prohibits the plugin from emitting code that is development-only.
 
-### template.optimizeSSR
+### `template.optimizeSSR`
 
 - type: `boolean`
 - default: `process.env.VUE_ENV === 'server'`
 
 Enable Vue 2.4 SSR compilation optimization that compiles part of the vdom trees returned by render functions into plain strings, which improves SSR performance. In some cases you might want to explicitly turn it off because the resulting render functions can only be used for SSR and cannot be used for client-side rendering or testing.
 
-### template.transpileOptions
+### `template.transpileOptions`
 
 - type: `Object`
 - default: `{}`
@@ -165,17 +166,17 @@ Configure ES2015+ to ES5 transpiling options for the generated render function c
 
 The template render functions compilation supports a special transform `stripWith` (enabled by default), which removes the `with` usage in generated render functions to make them strict-mode compliant.
 
-## normalizer
+## `normalizer`
 
 - type: `string`
 - default: `undefined`
 
-## styleInjector
+## `styleInjector`
 
 - type: `string`
 - default: `undefined`
 
-## styleInjectorSSR
+## `styleInjectorSSR`
 
 - type: `string`
 - default: `undefined`

docs/options.md

@@ -85,7 +85,8 @@
     "typescript": "^2.8.3",
     "vue": "^2.5.16",
     "vue-class-component": "^6.2.0",
-    "vue-template-compiler": "^2.5.16"
+    "vue-template-compiler": "^2.5.16",
+    "vuepress": "^0.13.0"
   },
   "peerDependencies": {
     "vue-template-compiler": "*"