站点配置

站点配置是你可以定义站点的全局设置的地方。应用配置选项定义了适用于每个 VitePress 站点的基本设置，无论使用什么主题。

概述

配置解析

配置文件总是从 <root>/.vitepress/config.[ext] 解析，其中 <root> 是你的 VitePress 项目根目录，[ext] 是支持的文件扩展名之一。开箱即用地支持 TypeScript。

.vitepress/config.js
.vitepress/config.ts
.vitepress/config.mjs
.vitepress/config.mts

建议使用 ES 模块语法：

export default {
  // 应用级配置选项
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',
  ...
}

配置智能提示

使用 defineConfig 辅助函数将为配置选项提供 TypeScript 支持的智能提示：

import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

VitePress 还直接支持 TS 配置文件。你也可以使用 .vitepress/config.ts 配合 defineConfig 辅助函数。

类型化主题配置

默认情况下，defineConfig 辅助函数期望默认主题配置类型：

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // 类型是 `DefaultTheme.Config`
  }
})

如果你使用自定义主题并希望对主题配置进行类型检查，你需要使用 defineConfigWithTheme 代替，并通过泛型参数传递自定义主题的配置类型：

import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // 类型是 `ThemeConfig`
  }
})

元数据

title

类型： string
默认值： VitePress
详细信息：
站点的标题。这将是所有页面标题的后缀，并显示在浏览器标签中。

export default {
  title: 'VitePress'
}

titleTemplate

类型： string | boolean
详细信息：
允许自定义每个页面的标题后缀或整个标题。

export default {
  title: 'VitePress',
  titleTemplate: 'Custom Suffix'
}

:title 符号将被替换为当前页面的标题：

export default {
  title: 'VitePress',
  titleTemplate: ':title - Custom Suffix'
}

设置为 false 来禁用标题后缀：

export default {
  title: 'VitePress',
  titleTemplate: false
}

description

类型： string
默认值： A VitePress site
详细信息：
站点的描述。这将在页面 HTML 中渲染为 <meta> 标签。

export default {
  description: 'A VitePress site'
}

head

类型： HeadConfig[]
默认值： []
详细信息：
要在页面 HTML 的 <head> 标签中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。

export default {
  head: [
    ['meta', { name: 'theme-color', content: '#3c8772' }],
    ['script', { src: 'https://example.com/script.js' }]
  ]
}

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

lang

类型： string
默认值： en-US
详细信息：
站点的 lang 属性。这将在页面 HTML 中渲染为 <html lang="en-US"> 标签。

export default {
  lang: 'en-US'
}

base

类型： string
默认值： /
详细信息：
站点将部署到的 base URL。如果你计划在子路径（例如 GitHub pages）下部署站点，则需要设置此选项。如果你计划将站点部署到 https://foo.github.io/bar/，那么你应该将 base 设置为 '/bar/'。它应该始终以斜杠开头和结尾。
base 会自动添加到其他选项中以 / 开头的所有 URL 前面，因此你只需要指定一次。

export default {
  base: '/base/'
}

路由

cleanUrls

类型： boolean
默认值： false
详细信息：
当设置为 true 时，VitePress 将从 URL 中删除尾随的 .html。另请参阅生成简洁的 URL。
需要服务器支持
启用此功能可能需要在你的托管平台上进行额外配置。要使其工作，你的服务器必须能够在访问 /foo 时提供 /foo.html 而不重定向。

rewrites

类型： Record<string, string>
详细信息：
定义自定义目录 <-> URL 映射。有关更多详细信息，请参阅路由：路由重写。

export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

构建

srcDir

类型： string
默认值： .
详细信息：
存储 markdown 页面的目录，相对于项目根目录。另请参阅根目录和源目录。

export default {
  srcDir: './src'
}

srcExclude

类型： string
默认值： undefined
详细信息：
用于匹配应作为源内容排除的 markdown 文件的 glob 模式。

export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir

类型： string
默认值： ./.vitepress/dist
详细信息：
站点的构建输出位置，相对于项目根目录（如果你正在运行 vitepress build docs，则相对于 docs 文件夹）。

export default {
  outDir: '../public'
}

cacheDir

类型： string
默认值： ./.vitepress/cache
详细信息：
缓存文件的目录，相对于项目根目录（如果你正在运行 vitepress build docs，则相对于 docs 文件夹）。另请参阅：cacheDir。

export default {
  cacheDir: './.vitepress/.vite'
}

ignoreDeadLinks

类型： boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]
默认值： false
详细信息：
当设置为 true 时，VitePress 不会因为死链接而导致构建失败。
当设置为 'localhostLinks' 时，构建将在死链接上失败，但不会检查 localhost 链接。

export default {
  ignoreDeadLinks: true
}

它也可以是一个字符串模式数组、正则表达式模式或自定义过滤函数。

export default {
  ignoreDeadLinks: [
    // 忽略精确 url "/playground"
    '/playground',
    // 忽略所有 localhost 链接
    /^https?:\/\/localhost/,
    // 忽略所有包含 "/repl/" 的链接
    /\/repl\//,
    // 自定义函数，忽略所有包含 "ignore "的链接
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

mpa

类型： boolean
默认值： false
详细信息：
当设置为 true 时，生产应用程序将在 MPA 模式下构建。MPA 模式默认提供 0kb JavaScript，代价是禁用客户端导航，并且需要明确选择加入交互性。

主题

appearance

类型： boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions
默认值： true
详细信息：
是否启用深色模式（通过将 .dark 类添加到 <html> 元素）。
- 如果选项设置为 true，则默认主题将由用户的首选配色方案确定。
- 如果选项设置为 dark，则默认情况下主题将是深色，除非用户手动切换它。
- 如果选项设置为 false，用户将无法切换主题。
此选项注入内联脚本，通过 vitepress-theme-appearance 键从本地存储恢复用户设置。这确保在渲染页面之前应用 .dark 类以避免闪烁。

lastUpdated

类型： boolean
默认值： false
详细信息：
是否使用 Git 获取每个页面的最后更新时间戳。时间戳将包含在每个页面的页面数据中，可通过 useData 访问。
使用默认主题时，启用此选项将显示每个页面的最后更新时间。你可以通过 themeConfig.lastUpdatedText 选项自定义文本。

export default {
  lastUpdated: true
}

自定义

markdown

类型： MarkdownOption
详细信息：
配置 Markdown 解析器选项。VitePress 使用 Markdown-it 作为解析器，使用 Shiki 来高亮不同语言语法。在此选项内，你可以传递各种 Markdown 相关选项以满足你的需要。

export default {
  markdown: {
    theme: 'material-theme-palenight',
    lineNumbers: true,
    
    // 调整 Markdown-it 设置
    config: (md) => {
      md.use(require('markdown-it-anchor'))
      md.use(require('markdown-it-toc'))
    }
  }
}

查看类型声明和 jsdocs 以获取所有可用选项。

vite

类型： import('vite').UserConfig
详细信息：
将原始 Vite 配置传递给内部 Vite 开发服务器/打包器。

export default {
  vite: {
    // Vite 配置选项
  }
}

vue

类型： import('@vitejs/plugin-vue').Options
详细信息：
将原始 @vitejs/plugin-vue 选项传递给内部插件实例。

export default {
  vue: {
    // @vitejs/plugin-vue 选项
  }
}

构建钩子

VitePress 构建钩子允许你向网站添加新功能和行为：

Sitemap
搜索索引
PWA
Teleports

buildEnd

类型： (siteConfig: SiteConfig) => Awaitable<void>
详细信息：
buildEnd 是一个构建 CLI 钩子，它将在构建 (SSG) 完成后但在 VitePress CLI 进程退出之前运行。

export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender

类型： (context: SSGContext) => Awaitable<SSGContext | void>
详细信息：
postRender 是一个构建钩子，在 SSG 渲染完成时调用。它将允许你在 SSG 期间处理 teleport 内容。

export default {
  async postRender(context) {
    // ...
  }
}

transformHead

类型： (context: TransformContext) => Awaitable<HeadConfig[]>
详细信息：
transformHead 是一个构建钩子，用于在生成每个页面之前转换 head。它将允许你添加无法静态添加到你的 VitePress 配置中的 head 条目。你只需要返回额外的条目，它们将自动与现有条目合并。
警告
不要改变 context 内的任何内容。

export default {
  async transformHead(context) {
    // ...
  }
}

transformHtml

类型： (code: string, id: string, context: TransformContext) => Awaitable<string | void>
详细信息：
transformHtml 是一个构建钩子，用于在保存到磁盘之前转换每个页面的内容。
警告
不要改变 context 内的任何内容。此外，修改 html 内容可能会导致客户端的激活问题。

export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData

类型： (pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>
详细信息：
transformPageData 是一个钩子，用于转换每个页面的 pageData。你可以直接改变 pageData 或返回将合并到 PageData 中的更改值。
警告
不要改变 context 内的任何内容，并且要小心这可能会影响开发服务器的性能，特别是如果你在钩子中有一些网络请求或繁重的计算。你可以检查 process.env.NODE_ENV === 'production' 来进行条件逻辑。

export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // 或返回要合并的数据
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}

站点配置 ​

概述 ​

配置解析 ​

配置智能提示 ​

类型化主题配置 ​

元数据 ​

title ​

titleTemplate ​

description ​

head ​

lang ​

base ​

路由 ​

cleanUrls ​

rewrites ​

构建 ​

srcDir ​

srcExclude ​

outDir ​

cacheDir ​

ignoreDeadLinks ​

mpa ​

主题 ​

appearance ​

lastUpdated ​

自定义 ​

markdown ​

vite ​

vue ​

构建钩子 ​

buildEnd ​

postRender ​

transformHead ​

transformHtml ​

transformPageData ​