配置

站点配置

base

  • 类型： string

  • 默认值： /

  • 详情：

    部署站点的基础路径。

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

    base 将会作为前缀自动地插入到以 / 开始的其他选项的链接中，所以你只需要指定一次。（head 中的属性除外）

    需要注意的是， 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 中。

    需要注意的是，如果 attrValue 是一个 pathname ，它不会被自动添加 base 前缀，所以如果需要的话请记得手动添加前缀。

  • 示例：

    增加一个自定义的 favicon ：

export default {
  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

  • 详情：

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

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

    • 使用 vuepress 或 vuepress-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 目录的。

permalinkPattern

  • 类型： string | null

  • 默认值： null

  • 详情：

    指定为页面生成永久链接的 Pattern 。

    它会被每个页面的 Frontmatter 中的 permalinkPattern 字段覆盖。

  • 参考：

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 模板路径。

templateBuildRenderer

  • 类型： TemplateRenderer

  • 默认值： templateRenderer

  • 详情：

    指定构建时使用的 HTML 模板渲染函数。

Markdown 配置

markdown

markdown.anchor

  • 类型： AnchorPluginOptions | false

  • 默认值：

const defaultOptions = {
  level: [1, 2, 3, 4, 5, 6],
  permalink: anchorPlugin.permalink.headerLink({
    class: 'header-anchor',
    safariReaderFix: true,
  }),
}

markdown.assets

  • 类型： AssetsPluginOptions | false

  • 详情：

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

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

警告

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

markdown.component

警告

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

markdown.emoji

markdown.frontmatter

警告

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

markdown.headers

  • 类型： HeadersPluginOptions | false

  • 默认值：

const defaultOptions = {
  level: [2, 3],
}

markdown.importCode

markdown.importCode.handleImportPath

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

  • 默认值： (str) => str

  • 详情：

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

  • 类型： LinkPluginOptions | false

  • 详情：

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

    它可以把站内链接的 tag 转换为 internalTag ，并且可以在站外链接上添加额外的属性和图标。

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

  • 参考：

  • 类型： string

  • 默认值： 'RouteLink'

  • 详情：

    内部链接所使用的标签。

    默认情况下，该插件会把内部链接转换为 RouteLink 。

  • 类型： Record<string, string>

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

  • 详情：

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

markdown.sfc

警告

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

markdown.slugify

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

  • 详情：

    默认使用的 slugify 函数。

markdown.title

  • 类型： undefined | false

  • 详情：

    @mdit-vue/plugin-title 插件的配置项。

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

警告

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

markdown.toc

  • 类型： TocPluginOptions | false

  • 默认值：

const defaultOptions = {
  level: [2, 3],
}

markdown.vPre.block

markdown.vPre.inline

插件配置

plugins

  • 类型： PluginConfig[]

  • 详情：

    要使用的插件。

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

  • 参考：

插件 API

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

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