Plugin API is supported by @vuepress/core package. You could check out Node API for how to use the VuePress app instance in plugin hooks.
Plugins should be used before initialization. The basic options will be handled once the plugin is used:
The following hooks will be processed when initializing app:
The following hooks will be processed when preparing files:
The following hooks will be processed in dev / build:
Check out Advanced > Architecture > Core Process and Hooks to understand the process better.
-
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 should follow the naming convention:
- Non-scoped:
vuepress-plugin-foo
- Scoped:
@org/vuepress-plugin-foo
- Non-scoped:
-
Also see:
-
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:
-
Type:
Record<string, any> | ((app: App, isServer: boolean) => Record<string, any>)
-
Details:
Path aliases definition.
This hook accepts an object or a function that returns an object.
-
Example:
import { getDirname, path } from '@vuepress/utils'
const __dirname = getDirname(import.meta.url)
export default {
alias: {
'@alias': path.resolve(__dirname, './path/to/alias'),
},
}
-
Type:
string | ((app: App) => string | Promise<string>)
-
Details:
Path of client config file.
This hook accepts an absolute file path, or a function that returns the path.
-
Example:
import { getDirname, path } from '@vuepress/utils'
const __dirname = getDirname(import.meta.url)
export default {
clientConfigFile: path.resolve(
__dirname,
'./path/to/clientConfig.js'
),
}
-
Type:
Record<string, any> | ((app: App, isServer: boolean) => 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:
export default {
define: {
__GLOBAL_BOOLEAN__: true,
__GLOBAL_STRING__: 'foobar',
__GLOBAL_OBJECT__: { foo: 'bar' },
},
}
-
Type:
(options: BundlerOptions, app: App) => void | Promise<void>
-
Details:
Bundler options extension.
This hook accepts a function that will receive the bundler options.
This hook can be used for modifying bundler options.
You could determine which bundler the user is using by
app.options.bundler.name
. -
Example:
Adding default app.compilerOptions.isCustomElement option:
export default {
extendsBundlerOptions: (bundlerOptions, app) => {
// extends options of @vuepress/bundler-vite
if (app.options.bundler.name === '@vuepress/bundler-vite') {
bundlerOptions.vuePluginOptions ??= {}
bundlerOptions.vuePluginOptions.template ??= {}
bundlerOptions.vuePluginOptions.template.compilerOptions ??= {}
const isCustomElement = bundlerOptions.vuePluginOptions.template.compilerOptions.isCustomElement
bundlerOptions.vuePluginOptions.template.compilerOptions.isCustomElement = (tag) => {
if (isCustomElement?.(tag)) return true
if (tag === 'my-custom-element') return true
}
}
// extends options of @vuepress/bundler-webpack
if (app.options.bundler.name === '@vuepress/bundler-webpack') {
bundlerOptions.vue ??= {}
bundlerOptions.vue.compilerOptions ??= {}
const isCustomElement = bundlerOptions.vue.compilerOptions.isCustomElement
bundlerOptions.vue.compilerOptions.isCustomElement = (tag) => {
if (isCustomElement?.(tag)) return true
if (tag === 'my-custom-element') return true
}
}
},
}
- Also see:
-
Type:
(options: MarkdownOptions, app: App) => void | Promise<void>
-
Details:
Markdown options extension.
This hook accepts a function that will receive the markdown options.
This hook can be used for modifying markdown options.
-
Example:
Modifying the default header levels that going to be extracted:
export default {
extendsMarkdownOptions: (markdownOptions, app) => {
if (markdownOptions.headers === false) return
markdownOptions.headers ??= {}
if (markdownOptions.headers.level) return
markdownOptions.headers.level = [2, 3, 4, 5, 6]
},
}
- Also see:
-
Type:
(md: Markdown, app: App) => void | Promise<void>
-
Details:
Markdown enhancement.
This hook accepts a function that will receive an instance of
Markdown
powered by markdown-it in its arguments.This hook can be used for using extra markdown-it plugins and implementing customizations.
-
Example:
export default {
extendsMarkdown: (md) => {
md.use(plugin1)
md.linkify.set({ fuzzyEmail: false })
},
}
-
Type:
(options: PageOptions, app: App) => void | Promise<void>
-
Details:
Page options extension.
This hook accepts a function that will receive the options of
createPage
.This hook can be used for modifying page options
-
Example:
Set permalink pattern for pages in _posts
directory:
export default {
extendsPageOptions: (pageOptions, app) => {
if (pageOptions.filePath?.startsWith(app.dir.source('_posts/'))) {
pageOptions.frontmatter = pageOptions.frontmatter ?? {}
pageOptions.frontmatter.permalinkPattern = '/:year/:month/:day/:slug.html'
}
},
}
- Also see:
-
Type:
(page: Page, app: App) => void | Promise<void>
-
Details:
Page extension.
This hook accepts a function that will receive a
Page
instance.This hook can be used for adding extra properties or modifying current properties on
Page
object.Notice that changes to
page.data
andpage.routeMeta
can be used in client side code. -
Example:
export default {
extendsPage: (page) => {
page.foo = 'foo'
page.data.bar = 'bar'
},
}
In client component:
import { usePageData } from '@vuepress/client'
export default {
setup() {
const page = usePageData()
console.log(page.value.bar) // bar
},
}
- Also see:
-
Type:
(app: App) => void | Promise<void>
-
Details:
This hook will be invoked once VuePress app has been initialized.
-
Type:
(app: App) => void | Promise<void>
-
Details:
This hook will be invoked once VuePress app has finished preparation.
-
Type:
(app: App, watchers: Closable[], restart: () => Promise<void>) => void | Promise<void>
-
Details:
This hook will be invoked once VuePress app has started dev-server and watched files change.
The
watchers
is an array of file watchers. When changing config file, the dev command will be restarted and those watchers will be closed. If you are adding new watchers in this hook, you should push your watchers to thewatchers
array, so that they can be closed correctly when restarting.The
restart
is a method to restart the dev command. When calling this method, thewatchers
array will be closed automatically.
-
Type:
(app: App) => void | Promise<void>
-
Details:
This hook will be invoked once VuePress app has generated static files.