fes.js/docs/reference/plugin-api.md

Plugin API

Plugins should be used before initialization. The basic options will be handled once the plugin is used:

• name
• multiple
• plugins

The following hooks will be processed when initializing app:

• extendsMarkdown
• onInitialized

The following hooks will be processed when preparing files:

• extendsPageData
• clientAppEnhanceFiles
• clientAppRootComponentFiles
• clientAppSetupFiles
• onPrepared

The following hooks will be processed in dev / build:

• alias
• define
• onGenerated

Basic Options

name

• Type: string

• Details:

  Name of the plugin.

  It will be used for identifying plugins to avoid using a same plugin multiple times, so make sure to use a unique plugin name.

  It is recommended to use following format:

  • Non-scoped: vuepress-plugin-foo
  • Scoped: @org/vuepress-plugin-foo

• Also see:

  • Plugin API > multiple

multiple

• Type: boolean

• Default: false

• Details:

  Declare whether the plugin can be used multiple times.

  If set to false, when using plugins with the same name, the one used previously will be replaced by the one used later.

  If set to true, plugins with the same name could be used multiple times and won't be replaced.

• Also see:

  • Plugin API > name

plugins

• Type: PluginConfig[]

• Details:

  Plugins to use.

  A plugin can use other plugins via this option.

  This option accepts an array, each item of which is a two-element tuple:

  • The first element is the plugin name or the plugin itself. It accepts plugin name, plugin name shorthand, absolute path to plugin, or the plugin object.
  • The second element is the plugin options. It accepts boolean or object. Set it to false to disable the plugin. Set it to true to enable the plugin without any options. Use object to enable the plugin with options.

  For simplicity, you can use the first element of the tuple that described above as the array item, which equals enabling the plugin without any options.

• Example:

module.exports = {
  plugins: [
    // two-element tuple
    ['vuepress-plugin-foo', false],
    ['bar', true],
    ['/path/to/local/plugin', { /* options */ }],
    [require('vuepress-plugin-baz'), true],

    // only use the first element
    'foobar', // equals to ['foobar', true]
  ],
}

• Also see:
  • Guide > Plugin

Development Hooks

alias

• Type: Record<string, any> | ((app: App) => Record<string, any>)

• Details:

  Path aliases definition.

  This hook accepts an object or a function that returns an object.

• Example:

module.exports = {
  alias: {
    '@alias': '/path/to/alias',
  },
}

define

• Type: Record<string, any> | ((app: App) => Record<string, any>)

• Details:

  Define global constants replacements.

  This hook accepts an object or a function that returns an object.

  This can be useful for passing variables to client files. Note that the values will be automatically processed by JSON.stringify().

• Example:

module.exports = {
  define: {
    __GLOBAL_BOOLEAN__: true,
    __GLOBAL_STRING__: 'foobar',
    __GLOBAL_OBJECT__: { foo: 'bar' },
  },
}

extendsMarkdown

• Type: (md: Markdown, app: App) => void

• Details:

  Markdown enhancement.

  This hook accepts a function that will receive an instance of Markdown powered by markdown-it in its arguments.

  This can be used for using extra markdown-it plugins and implementing customizations.

• Example:

module.exports = {
  extendsMarkdown: (md) => {
    md.use(plugin1)
    md.linkify.set({ fuzzyEmail: false })
  },
}

extendsPageData

• Type: (page: Page, app: App) => Record<string, any> | Promise<Record<string, any>>

• Details:

  Page data extension.

  This hook accepts a function that will receive an instance of Page. The returned object will be merged into page data, which can be used in client side code.

• Example:

module.exports = {
  extendsPageData: (page) => {
    const meta = 'foobar'
    return { meta }
  },
}

In client component:

import { usePageData } from '@vuepress/client'

export default {
  setup() {
    const page = usePageData()
    console.log(page.value.meta) // foobar
  },
}

Client Files Hooks

clientAppEnhanceFiles

• Type: string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)

• Details:

  Paths of client app enhancement files.

  This hook accepts absolute file paths, or a function that returns the paths.

• Example:

module.exports = {
  clientAppEnhanceFiles: '/path/to/clientAppEnhance.js',
}

clientAppRootComponentFiles

• Type: string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)

• Details:

  Paths of client app root component files.

  This hook accepts absolute file paths, or a function that returns the paths.

• Example:

module.exports = {
  clientAppRootComponentFiles: '/path/to/RootComponent.vue',
}

clientAppSetupFiles

• Type: string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)

• Details:

  Paths of client app setup files.

  This hook accepts absolute file paths, or a function that returns the paths.

• Example:

module.exports = {
  clientAppSetupFiles: '/path/to/clientAppSetup.js',
}

Lifecycle Hooks

onInitialized

• Type: (app: App) => void | Promise<void>

• Details:

  This hook will be invoked once VuePress app has been initialized.

onPrepared

• Type: (app: App) => void | Promise<void>

• Details:

  This hook will be invoked once VuePress app has finished preparation.

onGenerated

• Type: (app: App) => void | Promise<void>

• Details:

  This hook will be invoked once VuePress app has generated static files.