插件 API
插件 API 是由 @vuepress/core在新窗口打开 包支持的。你可以查看 Node API 来了解如何使用插件 Hooks 中的 VuePress App 实例。
概览
插件需要在初始化之前使用。基础配置项会在使用插件时立即被处理：
下列 Hooks 会在初始化 App 时处理：
下列 Hooks 会在准备文件时处理：
下列 Hooks 会在 dev / build 时处理：
查看 深入 > 架构 > 核心流程与 Hooks 来更好地理解该流程。
基础配置项
name
类型：
string详情：
插件的名称。
它会被用来识别插件，以避免多次使用同一个插件，因此应确保你的插件名称是独一无二的。
它应遵从如下命名约定：
- 非 Scoped:
vuepress-plugin-foo - Scoped:
@org/vuepress-plugin-foo
- 非 Scoped:
参考：
multiple
类型：
boolean默认值：
false详情：
插件是否能够被多次使用。
如果设置为
false，当有相同名称的插件被使用时，先使用的会被后使用的替换掉。如果设置为
true，相同名称的插件可以被多次使用且不会被替换。参考：
开发 Hooks
alias
类型：
Record<string, any> | ((app: App) => Record<string, any>)详情：
定义路径别名。
该 Hook 接收一个对象，或者一个返回对象的函数。
示例：
module.exports = {
alias: {
'@alias': path.resolve(__dirname, './path/to/alias'),
},
}
2
3
4
5
define
类型：
Record<string, any> | ((app: App) => Record<string, any>)详情：
定义全局常量。
该 Hook 接收一个对象，或者一个返回对象的函数。
它可以被用于向客户端文件传递变量。注意这里的值都会自动被
JSON.stringify()处理。示例：
module.exports = {
define: {
__GLOBAL_BOOLEAN__: true,
__GLOBAL_STRING__: 'foobar',
__GLOBAL_OBJECT__: { foo: 'bar' },
},
}
2
3
4
5
6
7
extendsMarkdown
类型：
(md: Markdown, app: App) => void | Promise<void>详情：
Markdown 增强。
该 Hook 接收一个函数，在参数中会收到一个由 markdown-it在新窗口打开 提供的
Markdown实例。它可以用来添加额外的 markdown-it 插件、应用额外的自定义功能。
示例：
module.exports = {
extendsMarkdown: (md) => {
md.use(plugin1)
md.linkify.set({ fuzzyEmail: false })
},
}
2
3
4
5
6
extendsPageOptions
类型：
(options: PageOptions, app: App) => PageOptions | Promise<PageOptions>详情：
页面配置项扩展。
该 Hook 接收一个函数，在参数中会收到
cretePage传入的原始选项。返回的对象会被合并到页面选项中，用以创建页面。示例：
为 _posts 目录下的页面设置永久链接 Pattern ：
module.exports = {
extendsPageOptions: ({ filePath }, app) => {
if (filePath?.startsWith(app.dir.source('_posts/'))) {
return {
frontmatter: {
permalinkPattern: '/:year/:month/:day/:slug.html',
},
}
}
return {}
},
}
2
3
4
5
6
7
8
9
10
11
12
extendsPageData
类型：
(page: Omit<Page, 'data'>, app: App) => Record<string, any> | Promise<Record<string, any>>详情：
页面数据扩展。
该 Hook 接收一个函数，在参数中会收到一个
Page实例 （不包含data属性）。返回的对象会被合并到页面数据中，可以在客户端代码中使用。示例：
module.exports = {
extendsPageData: (page) => {
const meta = 'foobar'
return { meta }
},
}
2
3
4
5
6
在客户端组件中：
import { usePageData } from '@vuepress/client'
export default {
setup() {
const page = usePageData()
console.log(page.value.meta) // foobar
},
}
2
3
4
5
6
7
8
客户端文件 Hooks
clientAppEnhanceFiles
类型：
string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)详情：
Client App Enhancement 文件路径。
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
该 Hook 中的文件会在客户端 App 创建后被调用，用以对其进行一些增强。
示例：
const { path } = require('@vuepress/utils')
module.exports = {
clientAppEnhanceFiles: path.resolve(__dirname, './path/to/clientAppEnhance.js'),
}
2
3
4
5
clientAppRootComponentFiles
类型：
string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)详情：
Client Root Component 文件路径。
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
该 Hook 中的组件会被渲染到客户端 App 的根节点。
示例：
const { path } = require('@vuepress/utils')
module.exports = {
clientAppRootComponentFiles: path.resolve(__dirname, './path/to/RootComponent.vue'),
}
2
3
4
5
clientAppSetupFiles
类型：
string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)详情：
Client App Setup 文件路径。
该 Hook 接收文件绝对路径，或者一个返回路径的函数。
该 Hook 中的文件会在客户端 App 的 setup在新窗口打开 函数中被调用。
示例：
const { path } = require('@vuepress/utils')
module.exports = {
clientAppSetupFiles: path.resolve(__dirname, './path/to/clientAppSetup.js'),
}
2
3
4
5
生命周期 Hooks
onInitialized
类型：
(app: App) => void | Promise<void>详情：
该 Hook 会在 VuePress App 初始化后被立即调用。
onPrepared
类型：
(app: App) => void | Promise<void>详情：
该 Hook 会在 VuePress App 完成文件准备后被立即调用。
onWatched
类型：
(app: App, watchers: Closable[], restart: () => Promise<void>) => void | Promise<void>详情：
该 Hook 会在 VuePress App 启动开发服务器并开始监听文件修改后被调用。
watchers是一个文件监听器的数组。在修改配置文件导致重启 dev 命令时，这些监听器会被自动关闭。如果你在当前 Hook 中添加了新的监听器，你应该把它们也加入到这个数组中，确保在重启 dev 命令时它们能被正确关闭。restart方法用来重启 dev 命令。调用该方法时，watchers数组中的监听器也会被自动关闭。
onGenerated
类型：
(app: App) => void | Promise<void>详情：
该 Hook 会在 VuePress App 完成静态文件生成后被立即调用。