配置

@vuepress/cli@vuepress/core

站点配置

base

  • 类型: string

  • 默认值: /

  • 详情:

    部署站点的基础路径。

    如果你想让你的网站部署到一个子路径下,你将需要设置它。它的值应当总是以斜杠开始,并以斜杠结束。举例来说,如果你想将你的网站部署到 https://foo.github.io/bar/,那么 base 应该被设置成 "/bar/"

    base 将会作为前缀自动地插入到所有以 / 开始的其他选项的链接中,所以你只需要指定一次。

  • 参考:

lang

  • 类型: string

  • 默认值: en-US

  • 详情:

    站点的语言。

    它将会在最终渲染出的 HTML 中作为 <html> 标签的 lang 属性。

    它可以设置在不同语言的 locales 中。

  • 参考:

title

  • 类型: string

  • 默认值: ''

  • 详情:

    站点的标题。

    它将会作为所有页面标题的后缀,并且在默认主题的导航栏中显示。

    它可以设置在不同语言的 locales 中。

  • 参考:

description

  • 类型: string

  • 默认值: ''

  • 详情:

    站点的描述。

    它将会在最终渲染出的 HTML 中作为 <meta name="description" /> 标签的 content 属性。它会被每个页面的 Frontmatter 中的 description 字段覆盖。

    它可以设置在不同语言的 locales 中。

  • 参考:

  • 类型: HeadConfig[]

  • 默认值: []

  • 详情:

    在最终渲染出的 HTML 的 <head> 标签内加入的额外标签。

    你可以通过 [tagName, { attrName: attrValue }, innerHTML?] 的格式来添加标签。

    它可以设置在不同语言的 locales 中。

  • 示例:

    增加一个自定义的 favicon :

module.exports = {
  head: [['link', { rel: 'icon', href: '/images/logo.png' }]],
}

渲染为:

<head>
  <link rel="icon" href="/images/logo.png" />
</head>

locales

  • 类型: { [path: string]: Partial<SiteLocaleData> }

  • 默认值: {}

  • 详情:

    多语言支持的各个语言 locales 。

    可以使用的字段有:

  • 参考:

主题配置

theme

打包工具配置

bundler

  • 类型: Bundler

  • 详情:

    设置站点要使用的打包工具。

    如果不设置该选项,将会使用默认的打包工具:

    • 使用 vuepressvuepress-vite 时,默认的打包工具是 Vite 。
    • 使用 vuepress-webpack 时,默认的打包工具是 Webpack 。
  • 参考:

通用配置项

dest

  • 类型: string

  • 默认值: `${sourceDir}/.vuepress/dist`

  • 详情:

    指定 vuepress build 命令的输出目录。

temp

  • 类型: string

  • 默认值: `${sourceDir}/.vuepress/.temp`

  • 详情:

    指定临时文件目录。

注意

VuePress 在开发和构建时会加载临时文件,因此临时文件目录应位于项目根目录内部,以便可以正确地解析到依赖。

cache

  • 类型: string

  • 默认值: `${sourceDir}/.vuepress/.cache`

  • 详情:

    指定缓存文件目录。

public

debug

  • 类型: boolean

  • 默认值: false

  • 详情:

    是否启用 Debug 模式。

    该配置项主要提供给开发者使用。同时,我们使用了 debug在新窗口打开 模块打印 Debug 日志,可以通过 DEBUG=vuepress* 环境变量来启用。

pagePatterns

  • 类型: string[]

  • 默认值: ['**/*.md', '!.vuepress', '!node_modules']

  • 详情:

    指定页面文件的 Patterns 。这些 Patterns 是相对于 Source 目录的。

Dev 配置项

host

  • 类型: string

  • 默认值: '0.0.0.0'

  • 详情:

    指定开发服务器的主机名。

port

  • 类型: number

  • 默认值: 8080

  • 详情:

    指定开发服务器的端口号。

open

  • 类型: boolean

  • 默认值: false

  • 详情:

    是否在开发服务器启动后打开浏览器。

templateDev

  • 类型: string

  • 默认值: '@vuepress/client/templates/dev.html'

  • 详情:

    指定开发时使用的 HTML 模板。

Build 配置项

shouldPreload

  • 类型: ((file: string, type: string) => boolean)) | boolean

  • 默认值: true

  • 详情:

    一个函数,用来控制哪些文件是需要生成对应的 <link rel="preload"> 标签的。设置为 true 或者 false 来完全启用或禁用它。

    默认情况下,只有当前页面所需的文件会被预加载。所以在绝大部分情况下,你只需要使用 true 就可以了。

shouldPrefetch

  • 类型: ((file: string, type: string) => boolean)) | boolean

  • 默认值: true

  • 详情:

    一个函数,用来控制哪些文件是需要生成对应的 <link rel="prefetch"> 标签的。设置为 true 或者 false 来完全启用或禁用它。

    如果你将它设置为 true ,所有其它页面所需的文件都会被预拉取。这对于小型站点来说是十分有帮助的,因为它会大大提升页面切换的速度。但是在你的网站有很多页面时不建议你这么做。

templateBuild

  • 类型: string

  • 默认值: '@vuepress/client/templates/build.html'

  • 详情:

    指定构建时使用的 HTML 模板。

Markdown 配置

markdown

markdown.anchor

markdown.assets

  • 类型: AssetsPluginOptions | false

  • 详情:

    VuePress 内置的 markdown-it assets 插件的配置项。

    设置为 false 可以禁用该插件。

警告

除非你了解它的用途,否则你不应该设置该配置项。

markdown.code

markdown.code.highlightLines

markdown.code.lineNumbers

  • 类型: boolean | number

  • 默认值: true

  • 详情:

    配置代码块行号。

    • 布尔值 boolean 代表是否启用代码块行号。
    • 数字 number 代表显示行号所需的最少行数。例如,如果你将它设置为 4 ,那么只有在你的代码块包含至少 4 行代码时才会启用行号。
  • 参考:

markdown.code.preWrapper

  • 类型: boolean

  • 默认值: true

  • 详情:

    是否在 <pre> 标签外额外包裹一层。

    highlightLineslineNumbers 依赖于这个额外的包裹层。这换句话说,如果你禁用了 preWrapper ,那么行高亮和行号也会被同时禁用。

提示

如果你想要在客户端来实现这些功能时,可以禁用该配置项。比如使用 Prismjs Line Highlight在新窗口打开 或者 Prismjs Line Numbers在新窗口打开

markdown.code.vPre.block

markdown.code.vPre.inline

markdown.customComponent

  • 类型: undefined | false

  • 详情:

    VuePress 内置的 markdown-it custom-component 插件的配置项。

    设置为 false 可以禁用该插件。

警告

除非你了解它的用途,否则你不应该设置该配置项。

markdown.emoji

markdown.extractHeaders

  • 类型: ExtractHeadersPluginOptions | false

  • 详情:

    VuePress 内置的 markdown-it extract-headers 插件的配置项。

    它将会把页面的子标题提取到 Page Data 中,可以用于生成侧边栏、目录等。比如当前页面的侧边栏,就是由这个插件提取出的标题来自动生成的。

    设置为 false 可以禁用该插件。

  • 参考:

markdown.extractHeaders.level

  • 类型: number[]

  • 默认值: [2, 3]

  • 详情:

    需要提取的子标题层级。

    举例来说,如果你把该选项设为 [2] ,那么只会提取 ## 子标题。

    它应该是 markdown.anchor.level 选项的一个子集,以便确保提取出来的链接是存在的。

markdown.extractHeaders.slugify

  • 类型: (str: string) => string

  • 详情:

    一个函数,根据原始的子标题来获取提取出的子标题 slug 。

    它应该使用和 markdown.anchor.slugify 选项相同的 slugify 函数,来确保链接是匹配的。

markdown.extractHeaders.format

  • 类型: ((str: string) => string) | undefined

  • 默认值: undefined

  • 详情:

    一个函数,将原始的子标题格式化为提取出的标题。

markdown.extractTitle

  • 类型: undefined | false

  • 详情:

    VuePress 内置的 markdown-it extract-title 插件的配置项。

    它将会把大标题提取到 Page Data 中,将会被用作页面标题。

    设置为 false 可以禁用该插件。

警告

除非你了解它的用途,否则你不应该设置该配置项。

markdown.hoistTags

markdown.hoistTags.customBlocks

  • 类型: string[]

  • 默认值: []

  • 详情:

    想要提升的 SFC 自定义块。

    默认情况下,只会提升 <script><style> 标签。你可以设置该选项以便在 Markdown 中支持自定义块。

    例如,如果你将该选项设置为 ['foo'] ,那么 Markdown 中的 <foo> 标签就会提升为 Vue SFC 的自定义块。需要提醒的是,为了处理自定义块,你还需要正确配置你的打包工具。

markdown.importCode

markdown.importCode.handleImportPath

  • 类型: (str: string) => string

  • 默认值: (str) => str

  • 详情:

    一个函数,用于处理导入代码语法中的文件导入路径。

  • 类型: LinkPluginOptions | false

  • 详情:

    VuePress 内置的 markdown-it 链接插件的配置项。

    它可以把站内链接转换为 <RouterLink> ,并且可以在站外链接上添加额外的属性和图标。

    设置为 false 可以禁用该插件。

  • 参考:

  • 类型: string

  • 默认值: 'RouterLink'

  • 详情:

    内部链接所使用的标签。

    默认情况下,该插件会把内部链接转换为 <RouterLink> 。你可以把该选项设置为 'a' 来禁用这个功能。

  • 类型: Record<string, string>

  • 默认值: { target: '_blank', rel: 'noopener noreferrer' }

  • 详情:

    为外部链接添加额外的属性。

markdown.toc

markdown.toc.pattern

  • 类型: RegExp

  • 默认值: /^\[\[toc\]\]$/i

  • 详情:

    识别 Markdown 中的目录语法的 Pattern 。

markdown.toc.slugify

  • 类型: (str: string) => string

  • 详情:

    一个函数,根据原始的子标题来获取目录中的子标题 slug 。

    它应该使用和 markdown.anchor.slugify 选项相同的 slugify 函数,来确保链接是匹配的。

markdown.toc.format

  • 类型: ((str: string) => string) | undefined

  • 默认值: undefined

  • 详情:

    一个函数,将原始的子标题格式化为目录中的标题。

markdown.toc.level

  • 类型: number[]

  • 默认值: [2, 3]

  • 详情:

    需要包含在目录中的子标题层级。

    举例来说,如果你把该选项设为 [2] ,那么只会包含 ## 子标题。

    它应该是 markdown.anchor.level 选项的一个子集,以便确保目录中的链接是存在的。

插件配置

plugins

  • 类型: PluginConfig[]

  • 详情:

    要使用的插件。

    该配置项接收一个数组,其中的每一个数组项是一个或一组插件。

  • 参考:

插件 API

用户配置文件同样可以作为一个 VuePress 插件,所以除了 namemultiple 配置项以外的所有插件 API 都可以在配置文件中使用。

前往 插件 API 参考 查看所有插件 API 。