Option API

    • Type:
    • Default: undefined

    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.

    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-chain.

    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 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. })
    • Type: Function
    • Default: undefined

    Equivalent to in webpack-dev-server. 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

    extendMarkdown

    • Type: Function
    • Default: undefined

    A function to edit default config or apply extra plugins to the 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 —— A chaining API like webpack-chainOption API - 图10 but for .

    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
    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 .

    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. }
    • 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 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'
    16.     // 2. Change frontmatter.
    17.     frontmatter.sidebar = 'auto'
    18.   }
    19. }

    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.

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

    clientRootMixin

    • Type: String
    • Default:

    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>
    • Type: function
    • Default: undefined

    Register a extra command to enhance the CLI of VuePress. The function will be called with a '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.   }

    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 as an CLI argument.