wip commit

docs/plugin/README.md

@@ -10,10 +10,10 @@ Plugins usually add global-level functionality to VuePress. There is no strictly
 
 1. Extend the data generated at compile time. e.g. `the last updated time of each file`.
 2. Generate extra files before or after compilation. e.g. `PWA support`.
-3. Add some extra pages.
-4. Add some global UI. e.g. `back to top`.
+3. Add extra pages. e.g. [vuepress-plugin-i18n-ui](https://github.com/ulivz/vuepress-plugin-i18n-ui)
+4. Inject global UI. e.g. `back to top`.
 
-A plugin should export a `plain object`(`#1`). If the plugin needs to take options, it can be a function that exports a plain object(`#2`). The function will be called with the plugin's options as the first argument, along with plugin's context which provides some compile-time context.
+A plugin should export a `plain object`(`#1`). If the plugin needs to take options, it can be a function that exports a plain object(`#2`). The function will be called with the plugin's options as the first argument, along with [plugin context](#plugin-context) which provides some compile-time context.
 
 ``` js
 // #1
@@ -79,6 +79,21 @@ module.exports = {
 
 The name of the plugin.
 
+### enable
+
+- Type: `boolean`
+- Default: true
+
+Configure whether to enable this plugin. e.g. if you want to enable a plugin only in development mode:
+
+``` js
+module.exports = (options, context) => {
+  return {
+    enable: !context.isProd
+  }
+}
+```
+
 ### chainWebpack
 
 - Type: `Function`
@@ -252,18 +267,18 @@ module.exports = {
 }
 ````
 
+## Plugin Context
 
+```
+module.exports = (options, context) => {
+  return {
+    enable: !context.isProd
+  }
+}
+```
 
 
-
-
-
-
-
-
-在正式介绍插件之前，我们需要花一些时间来了解 VuePress 的基本工作原理。
-
-## Lifecycle Diagram
+## Lifecycle
 
 首先，我们都知道 VuePress 有两个主要指令：
 
@@ -278,3 +293,13 @@ dev 和 build 的工作过程大抵相同，他们的基本工作流程如下:
 
 
 
+
+
+
+
+在正式介绍插件之前，我们需要花一些时间来了解 VuePress 的基本工作原理。
+
+
+
+
+

lib/build.js

@@ -16,7 +16,7 @@ module.exports = async function build (sourceDir, cliOptions = {}) {
   const { normalizeHeadTag, applyUserWebpackConfig } = require('./util')
 
   logger.wait('\nExtracting site metadata...')
-  const options = await prepare(sourceDir)
+  const options = await prepare(sourceDir, true /* isProd */)
   if (cliOptions.outDir) {
     options.outDir = cliOptions.outDir
   }

lib/dev.js

@@ -20,7 +20,7 @@ module.exports = async function dev (sourceDir, cliOptions = {}) {
   const { frontmatterEmitter } = require('./webpack/markdownLoader')
 
   logger.wait('\nExtracting site metadata...')
-  const options = await prepare(sourceDir)
+  const options = await prepare(sourceDir, false /* isProd */)
 
   // setup watchers to update options and dynamically generated files
   const update = () => {

lib/plugin-api/context.js

@@ -11,6 +11,10 @@ class PluginContext {
     })
   }
 
+  get isProd () {
+    return this._options.isProd
+  }
+
   get sourceDir () {
     return this._options.sourceDir
   }

lib/plugin-api/index.js

@@ -22,8 +22,17 @@ module.exports = class Plugin {
       // but also own the inheritance context.
       plugin = plugin(pluginOptions, Object.create(this._pluginContext))
     }
-    plugin = Object.assign(plugin, { name: inferPluginName(pluginRaw, plugin) })
-    this.applyPlugin(plugin)
+
+    plugin = Object.assign({
+      enabled: true,
+      name: inferPluginName(pluginRaw, plugin)
+    }, plugin)
+
+    if (plugin.enabled) {
+      this.applyPlugin(plugin)
+    } else {
+      logger.debug(`\n${chalk.gray(`[vuepress-plugin-${plugin.name}]`)} disabled.`)
+    }
     return this
   }
 

lib/prepare/index.js

@@ -6,9 +6,10 @@ const resolvePlugin = require('./resolvePlugin')
 const { genRoutesFile } = require('./codegen')
 const { writeTemp } = require('./util')
 
-module.exports = async function prepare (sourceDir) {
+module.exports = async function prepare (sourceDir, isProd) {
   // 1. load options
   const options = await resolveOptions(sourceDir)
+  options.isProd = isProd
   const { markdown } = options
 
   // 2. resolve plugin

packages/vuepress-plugin-active-header-links/index.js

@@ -2,6 +2,7 @@ const path = require('path')
 
 module.exports = (options, context) => ({
   name: 'active-header-links',
+  enable: context.isDev,
   // This mixin will be applied to the root component of each page.
   clientRootMixin: path.resolve(__dirname, 'mixin.js')
 })