VuePressVuePress
  • 介绍
  • 快速上手
  • 配置
  • 页面
  • Markdown
  • 静态资源
  • 多语言支持
  • 部署
  • 主题
  • 插件
  • 打包工具
  • 从 v1 迁移
  • 常见问题
  • 核心

    • 命令行接口
    • 配置
    • Frontmatter
    • 内置组件
    • 插件 API
    • 主题 API
    • 客户端 API
    • Node API
  • 打包工具

    • Vite
    • Webpack
  • 生态系统

    • 默认主题
    • 插件
  • 深入

    • 架构
    • 开发插件
    • 开发主题
    • Cookbook
  • 其他资源

    • 生态系统
    • 市场
    • 贡献指南
  • 更新日志
  • v1.x
  • v0.x
  • English
  • 简体中文
GitHub
  • 介绍
  • 快速上手
  • 配置
  • 页面
  • Markdown
  • 静态资源
  • 多语言支持
  • 部署
  • 主题
  • 插件
  • 打包工具
  • 从 v1 迁移
  • 常见问题
  • 核心

    • 命令行接口
    • 配置
    • Frontmatter
    • 内置组件
    • 插件 API
    • 主题 API
    • 客户端 API
    • Node API
  • 打包工具

    • Vite
    • Webpack
  • 生态系统

    • 默认主题
    • 插件
  • 深入

    • 架构
    • 开发插件
    • 开发主题
    • Cookbook
  • 其他资源

    • 生态系统
    • 市场
    • 贡献指南
  • 更新日志
  • v1.x
  • v0.x
  • English
  • 简体中文
GitHub
  • 核心

    • 命令行接口
    • 配置
    • Frontmatter
    • 内置组件
    • 插件 API
    • 主题 API
    • 客户端 API
    • Node API
  • 打包工具

    • Vite
    • Webpack
  • 生态系统

    • 默认主题
    • 插件

配置

站点配置

base

  • 类型: string

  • 默认值: /

  • 详情:

    部署站点的基础路径。

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

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

    需要注意的是, base 应该是一个以 / 开始和结束的绝对路径名。

  • 参考:

    • 指南 > 静态资源 > Base Helper
    • 指南 > 部署

lang

  • 类型: string

  • 默认值: en-US

  • 详情:

    站点的语言。

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

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

  • 参考:

    • 配置 > locales

title

  • 类型: string

  • 默认值: ''

  • 详情:

    站点的标题。

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

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

  • 参考:

    • 配置 > locales

description

  • 类型: string

  • 默认值: ''

  • 详情:

    站点的描述。

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

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

  • 参考:

    • 配置 > locales
    • Frontmatter > description

head

  • 类型: 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
    • Frontmatter > head

locales

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

  • 默认值: {}

  • 详情:

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

    可以使用的字段有:

    • lang
    • title
    • description
    • head
  • 参考:

    • 指南 > I18n

主题配置

theme

  • 类型: Theme

  • 详情:

    设置站点要使用的主题。

    如果不设置该选项,将会使用默认主题。

  • 参考:

    • 指南 > 主题
    • 默认主题 > 配置

打包工具配置

bundler

  • 类型: Bundler

  • 详情:

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

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

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

    • 指南 > 打包工具
    • 打包工具 > Vite
    • 打包工具 > Webpack

通用配置项

dest

  • 类型: string

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

  • 详情:

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

temp

  • 类型: string

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

  • 详情:

    指定临时文件目录。

注意

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

cache

  • 类型: string

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

  • 详情:

    指定缓存文件目录。

public

  • 类型: string

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

  • 详情:

    指定 Public 文件目录。

  • 参考:

    • 指南 > 静态资源 > 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 字段覆盖。

  • 参考:

    • 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

  • 类型: MarkdownOptions

  • 默认值: {}

  • 详情:

    对 VuePress 内置的 Markdown 语法扩展进行配置。

    它可以接收 markdown-it 的所有配置项,以及下列额外的配置项。

  • 参考:

    • markdown-it > Init with presets and options
    • 指南 > Markdown > 语法扩展

markdown.anchor

  • 类型: AnchorPluginOptions | false

  • 默认值:

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

    markdown-it-anchor 的配置项。

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

  • 参考:

    • 指南 > Markdown > 语法扩展 > 标题锚点

markdown.assets

  • 类型: AssetsPluginOptions | false

  • 详情:

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

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

警告

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

markdown.component

  • 类型: undefined | false

  • 详情:

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

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

警告

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

markdown.emoji

  • 类型: EmojiPluginOptions | false

  • 详情:

    markdown-it-emoji 的配置项。

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

  • 参考:

    • 指南 > Markdown > 语法扩展 > Emoji

markdown.frontmatter

  • 类型: FrontmatterPluginOptions | false

  • 详情:

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

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

  • 参考:

    • 指南 > 页面 > Frontmatter
    • Node API > Page 属性 > frontmatter

警告

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

markdown.headers

  • 类型: HeadersPluginOptions | false

  • 默认值:

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

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

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

  • 参考:

    • Node API > Page 属性 > headers

markdown.importCode

  • 类型: ImportCodePluginOptions | false

  • 详情:

    VuePress 内置的 markdown-it 导入代码插件的配置项。

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

  • 参考:

    • 指南 > Markdown > 语法扩展 > 导入代码块

markdown.importCode.handleImportPath

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

  • 默认值: (str) => str

  • 详情:

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

markdown.links

  • 类型: LinkPluginOptions | false

  • 详情:

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

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

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

  • 参考:

    • 指南 > Markdown > 语法扩展 > 链接

markdown.links.internalTag

  • 类型: string

  • 默认值: 'RouteLink'

  • 详情:

    内部链接所使用的标签。

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

markdown.links.externalAttrs

  • 类型: Record<string, string>

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

  • 详情:

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

markdown.sfc

  • 类型: SfcPluginOptions | false

  • 详情:

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

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

  • 参考:

    • Cookbook > Markdown 与 Vue SFC
    • Node API > Page 属性 > sfcBlocks

警告

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

markdown.slugify

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

  • 详情:

    默认使用的 slugify 函数。

markdown.title

  • 类型: undefined | false

  • 详情:

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

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

警告

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

markdown.toc

  • 类型: TocPluginOptions | false

  • 默认值:

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

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

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

  • 参考:

    • 指南 > Markdown > 语法扩展 > 目录

markdown.vPre.block

  • 类型: boolean

  • 默认值: true

  • 详情:

    是否在代码块的 <pre> 标签上添加 v-pre 指令。

  • 参考:

    • 指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre

markdown.vPre.inline

  • 类型: boolean

  • 默认值: true

  • 详情:

    是否在行内代码的 <code> 标签上添加 v-pre 指令。

  • 参考:

    • 指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre

插件配置

plugins

  • 类型: PluginConfig[]

  • 详情:

    要使用的插件。

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

  • 参考:

    • 指南 > 插件

插件 API

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

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

在 GitHub 上编辑此页
上次更新: 2024/7/14 14:29
贡献者: meteorlxy, Mr.Hope, lebennington
Prev
命令行接口
Next
Frontmatter