站点配置
站点配置允许您定义站点的全局设置。应用程序配置选项定义适用于每个 VitePress 站点的设置,无论它使用哪个主题。例如,基本目录或站点的标题。
概述
配置解析
配置文件始终从 <root>/.vitepress/config.[ext]
解析,其中 <root>
是您的 VitePress 项目根目录,[ext]
是支持的文件扩展名之一。TypeScript 默认支持。支持的扩展名包括 .js
、.ts
、.mjs
和 .mts
。
建议在配置文件中使用 ES 模块语法。配置文件应默认导出一个对象
export default {
// app level config options
lang: 'en-US',
title: 'VitePress',
description: 'Vite & Vue powered static site generator.',
...
}
动态(异步)配置
如果您需要动态生成配置,您也可以默认导出一个函数。例如
import { defineConfig } from 'vitepress'
export default async () => {
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
return defineConfig({
// app level config options
lang: 'en-US',
title: 'VitePress',
description: 'Vite & Vue powered static site generator.',
// theme level config options
themeConfig: {
sidebar: [
...posts.map((post) => ({
text: post.name,
link: `/posts/${post.name}`
}))
]
}
})
}
您也可以使用顶层的 await
。例如
import { defineConfig } from 'vitepress'
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
export default defineConfig({
// app level config options
lang: 'en-US',
title: 'VitePress',
description: 'Vite & Vue powered static site generator.',
// theme level config options
themeConfig: {
sidebar: [
...posts.map((post) => ({
text: post.name,
link: `/posts/${post.name}`
}))
]
}
})
配置智能提示
使用 defineConfig
助手将为配置选项提供 TypeScript 支持的智能提示。假设您的 IDE 支持它,这应该在 JavaScript 和 TypeScript 中都有效。
import { defineConfig } from 'vitepress'
export default defineConfig({
// ...
})
类型化主题配置
默认情况下,defineConfig
助手期望主题配置类型来自默认主题
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
// Type is `DefaultTheme.Config`
}
})
如果您使用自定义主题并希望对主题配置进行类型检查,您需要使用 defineConfigWithTheme
,并通过泛型参数传递自定义主题的配置类型
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'
export default defineConfigWithTheme<ThemeConfig>({
themeConfig: {
// Type is `ThemeConfig`
}
})
Vite、Vue 和 Markdown 配置
Vite
您可以使用 VitePress 配置中的 vite 选项来配置底层 Vite 实例。无需创建单独的 Vite 配置文件。
Vue
VitePress 已经包含了 Vite 的官方 Vue 插件 (@vitejs/plugin-vue)。您可以使用 VitePress 配置中的 vue 选项来配置其选项。
Markdown
您可以使用 VitePress 配置中的 markdown 选项来配置底层的 Markdown-It 实例。
站点元数据
title
- 类型:
string
- 默认值:
VitePress
- 可以通过 前置信息 在每个页面上覆盖
站点的标题。使用默认主题时,这将显示在导航栏中。
它也将用作所有单个页面标题的默认后缀,除非定义了 titleTemplate
。单个页面的最终标题将是其第一个 <h1>
标题的文本内容,与全局 title
结合作为后缀。例如,使用以下配置和页面内容
export default {
title: 'My Awesome Site'
}
# Hello
页面的标题将是 Hello | My Awesome Site
。
titleTemplate
- 类型:
string | boolean
- 可以通过 前置信息 在每个页面上覆盖
允许自定义每个页面的标题后缀或整个标题。例如
export default {
title: 'My Awesome Site',
titleTemplate: 'Custom Suffix'
}
# Hello
页面的标题将是 Hello | Custom Suffix
。
要完全自定义标题的呈现方式,您可以在 titleTemplate
中使用 :title
符号
export default {
titleTemplate: ':title - Custom Suffix'
}
这里 :title
将被替换为从页面的第一个 <h1>
标题推断出的文本。前面示例页面的标题将是 Hello - Custom Suffix
。
该选项可以设置为 false
以禁用标题后缀。
description
- 类型:
string
- 默认值:
A VitePress site
- 可以通过 前置信息 在每个页面上覆盖
站点的描述。这将在页面 HTML 中呈现为 <meta>
标签。
export default {
description: 'A VitePress site'
}
head
- 类型:
HeadConfig[]
- 默认值:
[]
- 可以通过 前置信息 在每个页面上追加
在页面 HTML 的 <head>
标签中呈现的额外元素。用户添加的标签在关闭 head
标签之前呈现,在 VitePress 标签之后。
type HeadConfig =
| [string, Record<string, string>]
| [string, Record<string, string>, string]
示例:添加一个 favicon
export default {
head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // put favicon.ico in public directory, if base is set, use /base/favicon.ico
/* Would render:
<link rel="icon" href="/favicon.ico">
*/
示例:添加 Google Fonts
export default {
head: [
[
'link',
{ rel: 'preconnect', href: 'https://fonts.googleapis.com' }
],
[
'link',
{ rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
],
[
'link',
{ href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
]
]
}
/* Would render:
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
*/
示例:注册一个 service worker
export default {
head: [
[
'script',
{ id: 'register-sw' },
`;(() => {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js')
}
})()`
]
]
}
/* Would render:
<script id="register-sw">
;(() => {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js')
}
})()
</script>
*/
示例:使用 Google Analytics
export default {
head: [
[
'script',
{ async: '', src: 'https://127.0.0.1/gtag/js?id=TAG_ID' }
],
[
'script',
{},
`window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');`
]
]
}
/* Would render:
<script async src="https://127.0.0.1/gtag/js?id=TAG_ID"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');
</script>
*/
lang
- 类型:
string
- 默认值:
en-US
站点的 lang 属性。这将在页面 HTML 中呈现为 <html lang="en-US">
标签。
export default {
lang: 'en-US'
}
base
- 类型:
string
- 默认值:
/
站点将部署到的基本 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
网站的构建输出位置,相对于 项目根目录。
export default {
outDir: '../public'
}
assetsDir
- 类型:
string
- 默认值:
assets
指定嵌套生成的资产的目录。路径应位于 outDir
内,并相对于它解析。
export default {
assetsDir: 'static'
}
cacheDir
- 类型:
string
- 默认值:
./.vitepress/cache
缓存文件的目录,相对于 项目根目录。另请参阅:cacheDir。
export default {
cacheDir: './.vitepress/.vite'
}
ignoreDeadLinks
- 类型:
boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]
- 默认值:
false
设置为 true
时,VitePress 不会因死链接而导致构建失败。
设置为 'localhostLinks'
时,构建将因死链接而失败,但不会检查 localhost
链接。
export default {
ignoreDeadLinks: true
}
它也可以是精确 URL 字符串、正则表达式模式或自定义过滤器函数的数组。
export default {
ignoreDeadLinks: [
// ignore exact url "/playground"
'/playground',
// ignore all localhost links
/^https?:\/\/localhost/,
// ignore all links include "/repl/""
/\/repl\//,
// custom function, ignore all links include "ignore"
(url) => {
return url.toLowerCase().includes('ignore')
}
]
}
metaChunk 实验性
- 类型:
boolean
- 默认值:
false
设置为 true
时,将页面元数据提取到单独的 JavaScript 块中,而不是将其内联到初始 HTML 中。这使得每个页面的 HTML 负载更小,并使页面元数据可缓存,从而在网站中包含多个页面时减少服务器带宽。
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
类,以避免闪烁。
appearance.initialValue
只能是 'dark' | undefined
。不支持 Refs 或 Getter。
lastUpdated
- 类型:
boolean
- 默认值:
false
是否使用 Git 获取每个页面的最后更新时间戳。时间戳将包含在每个页面的页面数据中,可以通过 useData
访问。
使用默认主题时,启用此选项将显示每个页面的最后更新时间。您可以通过 themeConfig.lastUpdatedText
选项自定义文本。
自定义
markdown
- 类型:
MarkdownOption
配置 Markdown 解析器选项。VitePress 使用 Markdown-it 作为解析器,并使用 Shiki 来突出显示语言语法。在此选项中,您可以传递各种与 Markdown 相关的选项以满足您的需求。
export default {
markdown: {...}
}
查看 类型声明和 jsdocs 以了解所有可用的选项。
vite
- 类型:
import('vite').UserConfig
将原始 Vite 配置 传递给内部 Vite 开发服务器/捆绑器。
export default {
vite: {
// Vite config options
}
}
vue
- 类型:
import('@vitejs/plugin-vue').Options
将原始 @vitejs/plugin-vue
选项 传递给内部插件实例。
export default {
vue: {
// @vitejs/plugin-vue options
}
}
构建钩子
VitePress 构建钩子允许您为您的网站添加新功能和行为
- 站点地图
- 搜索索引
- PWA
- 传送
buildEnd
- 类型:
(siteConfig: SiteConfig) => Awaitable<void>
buildEnd
是一个构建 CLI 钩子,它将在构建(SSG)完成但 VitePress CLI 进程退出之前运行。
export default {
async buildEnd(siteConfig) {
// ...
}
}
postRender
- 类型:
(context: SSGContext) => Awaitable<SSGContext | void>
postRender
是一个构建钩子,在 SSG 渲染完成后调用。它将允许您在 SSG 期间处理传送内容。
export default {
async postRender(context) {
// ...
}
}
interface SSGContext {
content: string
teleports?: Record<string, string>
[key: string]: any
}
transformHead
- 类型:
(context: TransformContext) => Awaitable<HeadConfig[]>
transformHead
是一个构建钩子,用于在生成每个页面之前转换头部。它将允许您添加无法静态添加到 VitePress 配置中的头部条目。您只需要返回额外的条目,它们将自动与现有条目合并。
警告
不要修改 context
中的任何内容。
export default {
async transformHead(context) {
// ...
}
}
interface TransformContext {
page: string // e.g. index.md (relative to srcDir)
assets: string[] // all non-js/css assets as fully resolved public URL
siteConfig: SiteConfig
siteData: SiteData
pageData: PageData
title: string
description: string
head: HeadConfig[]
content: string
}
请注意,此钩子仅在静态生成网站时调用。它不会在开发期间调用。如果您需要在开发期间添加动态头部条目,可以使用 transformPageData
钩子。
export default {
transformPageData(pageData) {
pageData.frontmatter.head ??= []
pageData.frontmatter.head.push([
'meta',
{
name: 'og:title',
content:
pageData.frontmatter.layout === 'home'
? `VitePress`
: `${pageData.title} | VitePress`
}
])
}
}
示例:添加规范 URL <link>
export default {
transformPageData(pageData) {
const canonicalUrl = `https://example.com/${pageData.relativePath}`
.replace(/index\.md$/, '')
.replace(/\.md$/, '.html')
pageData.frontmatter.head ??= []
pageData.frontmatter.head.push([
'link',
{ rel: 'canonical', href: canonicalUrl }
])
}
}
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
或返回将合并到页面数据中的更改值。
警告
不要修改 context
中的任何内容,并注意这可能会影响开发服务器的性能,尤其是在钩子中包含一些网络请求或繁重的计算(如生成图像)时。您可以检查 process.env.NODE_ENV === 'production'
以进行条件逻辑。
export default {
async transformPageData(pageData, { siteConfig }) {
pageData.contributors = await getPageContributors(pageData.relativePath)
}
// or return data to be merged
async transformPageData(pageData, { siteConfig }) {
return {
contributors: await getPageContributors(pageData.relativePath)
}
}
}
interface TransformPageContext {
siteConfig: SiteConfig
}