Option API

name

  • Type: string
  • Default: undefined

The name of the plugin.

Internally, VuePress will use the plugin’s package name as the plugin name. When your plugin is a local plugin (that is using a pure plugin function directly), please be sure to configure this option, that is good for debug tracking.

  1. // .vuepress/config.js
  2. module.exports = {
  3.   plugins: [
  4.     [
  5.       (pluginOptions, context) => ({
  6.         name: 'my-xxx-plugin'
  7.         // ... the rest of options
  8.       })
  9.     ]
  10.   ]
  11. }

plugins

  • Type: array
  • Default: undefined

A plugin can contain several plugins like a preset.

  1. // A plugin
  2. module.exports = {
  3.   plugins: [
  4.     'tag',
  5.     'category'
  6.   ]
  7. }

chainWebpack

  • Type: Function
  • Default: undefined

Edit the internal webpack config with webpack-chainOption API - 图1.

  1. module.exports = {
  2.   chainWebpack (config, isServer) {
  3.     // config is an instance of ChainableConfig
  4.   }
  5. }

TIP

Since VuePress is a Vue-SSR based application, there needs to be two webpack configurations, isServer is used to determine whether the current webpack config is applied to the server or client.

Also see:

define

  • Type: Object|Function
  • Default: undefined

Since using DefinePluginOption API - 图3 via chainWebpack would be a little complicated:

  1. module.exports = {
  2.   chainWebpack (config) {
  3.     config.plugin('injections').tap(([options]) => [
  4.       Object.assign(options, {
  5.         SW_BASE_URL: JSON.stringify('/')
  6.       })
  7.     ])
  8.   }
  9. }

VuePress opened up a more concise define option, note that the values has been automatically processed by JSON.stringify.

  • Object Usage:
  1. module.exports = {
  2.   define: {
  3.     SW_BASE_URL: '/',
  4.   }
  5. }
  • Function Usage:
  1. module.exports = (options, context) => ({
  2.   define () {
  3.     return {
  4.       SW_BASE_URL: context.base || '/',
  5.       SW_ENABLED: !!options.enabled,
  6.     }
  7.   }
  8. })

alias

  • Type: Object|Function
  • Default: undefined

We can set aliases via chainWebpack:

  1. module.exports = (options, context) => ({
  2.   chainWebpack (config) {
  3.     config.resolve.alias.set('@pwd', process.cwd())
  4.   }
  5. })

But alias option makes this process more like configuration:

  1. module.exports = (options, context) => ({
  2.   alias: {
  3.     '@pwd': process.cwd()
  4.   }
  5. })

beforeDevServer

  • Type: Function
  • Default: undefined

Equivalent to beforeOption API - 图4 in webpack-dev-serverOption API - 图5. You can use it to define custom handlers before all middleware is executed:

  1. module.exports = {
  2.   // ...
  3.   beforeDevServer(app, server) {
  4.     app.get('/path/to/your/custom', function(req, res) {
  5.       res.json({ custom: 'response' })
  6.     })
  7.   }
  8. }

afterDevServer

  • Type: Function
  • Default: undefined

Equivalent to afterOption API - 图6 in webpack-dev-serverOption API - 图7. You can use it to execute custom middleware after all other middleware:

  1. module.exports = {
  2.   // ...
  3.   afterDevServer(app, server) {
  4.     // hacking now ...
  5.   }
  6. }

extendMarkdown

  • Type: Function
  • Default: undefined

A function to edit default config or apply extra plugins to the markdown-itOption API - 图8 instance used to render source files. Example:

  1. module.exports = {
  2.   extendMarkdown: md => {
  3.     md.set({ breaks: true })
  4.     md.use(require('markdown-it-xxx'))
  5.   }
  6. }

chainMarkdown

  • Type: Function
  • Default: undefined

Edit the internal Markdown config with markdown-it-chainOption API - 图9 —— A chaining API like webpack-chainOption API - 图10 but for markdown-itOption API - 图11.

  1. module.exports = {
  2.   chainMarkdown (config) {
  3.     // Interact with 'options' in new MarkdownIt
  4.     // Ref: https://markdown-it.github.io/markdown-it/#MarkdownIt.new
  5.     config
  6.       .options
  7.         .link(true)
  8.         .breaks(true)
  10.     // Modify the arguments of internal plugin.
  11.     config
  12.       .plugin('anchor')
  13.         .tap(([options]) => [
  14.           Object.assign(options, { permalinkSymbol: '#' })
  15.         ])
  17.     // Add extra markdown-it plugin
  18.     config
  19.       .plugin('sup')
  20.         .use(require('markdown-it-sup'))
  22.     // Remove internal plugin
  23.     config.plugins.delete('snippet')
  24.   }
  25. }

Also see:

enhanceAppFiles

  • Type: String | Array | AsyncFunction
  • Default: undefined

This option accepts absolute file path(s) pointing to the enhancement file(s), or a function that returns the path(s), which allows you to do some App Level Enhancements.

  1. import { resolve } from 'path'
  3. module.exports = {
  4.   enhanceAppFiles: resolve(__dirname, 'client.js')
  5. }

This option also supports dynamic code which allows you to do more, with the ability to touch the compilation context:

  1. module.exports = (option, context) => {
  2.   return {
  3.     enhanceAppFiles() {
  4.       return {
  5.          name: 'dynamic-code',
  6.          content: `export default ({ Vue }) => { Vue.mixin('$source', '${
  7.            context.sourceDir
  8.          }') }`
  9.        }
  10.     }
  11.   }
  12. }

clientDynamicModules

  • Type: Function
  • Default: undefined

Sometimes, you may want to generate some client modules at compile time.

  1. module.exports = (options, context) => ({
  2.   clientDynamicModules() {
  3.     return {
  4.       name: 'constants.js',
  5.       content: `export const SOURCE_DIR = '${context.sourceDir}'`
  6.     }
  7.   }
  8. })

Then you can use this module at client-side code by:

  1. import { SOURCE_DIR } from '@dynamic/constants'

extendPageData

  • Type: Function|AsyncFunction
  • Default: undefined

A function used to extend or edit the $page object. This function will be invoking once for each page at compile time.

  1. module.exports = {
  2.   extendPageData ($page) {
  3.     const {
  4.       _filePath,           // file's absolute path
  5.       _computed,           // access the client global computed mixins at build time, e.g _computed.$localePath.
  6.       _content,            // file's raw content string
  7.       _strippedContent,    // file's content string without frontmatter
  8.       key,                 // page's unique hash key
  9.       frontmatter,         // page's frontmatter object
  10.       regularPath,         // current page's default link (follow the file hierarchy)
  11.       path,                // current page's real link (use regularPath when permalink does not exist)
  12.     } = $page
  14.     // 1. Add extra fields.
  15.     $page.xxx = 'xxx'
  17.     // 2. Change frontmatter.
  18.     frontmatter.sidebar = 'auto'
  19.   }
  20. }

Note that extendPageData can also be defined as an asynchronous function.

  1. module.exports = {
  2.   async extendPageData ($page) {
  3.     $page.xxx = await getAsyncData()
  4.   }
  5. }

Note

These fields starting with an _ means you can only access them during build time.

For example:

  1. module.exports = {
  2.   extendPageData ($page) {
  3.     $page.size = ($page._content.length / 1024).toFixed(2) + 'kb'
  4.   }
  5. }

Then you can use this value via this.$page.size in any Vue component.

clientRootMixin

  • Type: String
  • Default: undefined

A path to the mixin file which allows you to control the lifecycle of root component.

  1. // plugin's entry
  2. const path = require('path')
  4. module.exports = {
  5.   clientRootMixin: path.resolve(__dirname, 'mixin.js')
  6. }
  1. // mixin.js
  2. export default {
  3.   created () {},
  4.   mounted () {}
  5. }

additionalPages

  • Type: Array|AsyncFunction
  • Default: undefined

Add a page pointing to a Markdown file:

  1. const path = require('path')
  3. module.exports = {
  4.   additionalPages: [
  5.     {
  6.      path: '/readme/',
  7.      filePath: path.resolve(__dirname, '../../README.md')
  8.     }
  9.   ]
  10. }

Add a page with explicit content:

  1. module.exports = {
  2.   async additionalPages () {
  3.     // Note that VuePress doesn't have request library built-in
  4.     // you need to install it yourself.
  5.     const rp = require('request-promise')
  6.     const content = await rp('https://raw.githubusercontent.com/vuejs/vuepress/master/CHANGELOG.md')
  7.     return [
  8.       {
  9.         path: '/changelog/',
  10.         content
  11.       }
  12.     ]
  13.   }
  14. }

Add a pure route:

  1. module.exports = {
  2.   additionalPages: [
  3.     {
  4.        path: '/alpha/',
  5.        frontmatter: {
  6.           layout: 'MyLayout'
  7.        }
  8.     }
  9.   ]
  10. }

globalUIComponents

  • Type: Array|String
  • Default: undefined

You might want to inject some global UI fixed somewhere on the page, for example back-to-top, popup. In VuePress, a global UI is a Vue component, you can directly define the component’s name(s) in this option, for example:

  1. module.exports = {
  2.   globalUIComponents: [
  3.     'Component-1',
  4.     'Component-2'
  5.   ]
  6. }

Then, VuePress will automatically inject these components behind the layout component:

  1. <div id="app">
  2.   <div class="theme-container"> ... </div> <!-- Layout Component -->
  3.   <div class="global-ui">
  4.     <Component-1/>
  5.     <Component-2/>
  6.   </div>
  7. </div>

extendCli

  • Type: function
  • Default: undefined

Register a extra command to enhance the CLI of VuePress. The function will be called with a CACOption API - 图14's instance as the first argument.

  1. module.exports = {
  2.   extendCli (cli) {
  3.     cli
  4.       .command('info [targetDir]', '')
  5.       .option('--debug', 'display info in debug mode')
  6.       .action((dir = '.') => {
  7.         console.log('Display info of your website')
  8.       })
  9.   }
  10. }

Now you can use vuepress info [targetDir] a in your project!

TIP

Note that a custom command registered by a plugin requires VuePress to locate your site configuration like vuepress dev and vuepress build, so when developing a command, be sure to lead the user to pass targetDir as an CLI argument.