站点配置

站点配置可以定义站点的全局设置。应用配置选项适用于每个 VitePress 站点，无论它使用什么主题。例如根目录或站点的标题。

配置文件

配置文件总是从 .vitepress/config.[ext] 解析，[ext] 是支持的文件扩展名之一。开箱即用地支持 TypeScript。支持的扩展名包括 .js、.ts、.mjs 和 .mts。

typescript

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

异步的动态配置

如果需要动态生成配置，也可以默认导出一个函数：

typescript

import { defineConfig } from 'vitepress'

export default async () => {
  const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

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

    // 主题级配置选项
    themeConfig: {
      sidebar: [
        ...posts.map((post) => ({
          text: post.name,
          link: `/posts/${post.name}`
        }))
      ]
    }
  })
}

也可以在最外层使用 await：

typescript

import { defineConfig } from 'vitepress'

const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

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

配置智能提示

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

typescript

import { defineConfig } from 'vitepress'

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

主题类型提示

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

typescript

import { defineConfig } from 'vitepress'

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

如果使用自定义主题并希望对主题配置进行类型检查，则需要改用 defineConfigWithTheme：

typescript

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

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // 类型为 `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`	自定义每个页面的标题后缀或整个标题	`string \| boolean`	-
`description`	站点的描述，将呈现为页面 HTML 中的 `<meta>` 标签	`string`	`A VitePress site`
`head`	要在页面 HTML 的 `<head>` 标签中呈现的其他元素	`HeadConfig[]`	`[]`
`lang`	站点的语言属性	`string`	`en-US`
`base`	站点将部署的 base URL	`string`	`/`
`srcDir`	源目录相对于项目根目录的位置	`string`	`.`
`publicDir`	公共目录的位置	`string`	`public`
`outDir`	构建输出目录	`string`	`.vitepress/dist`
`assetsDir`	静态资源目录	`string`	`assets`
`cacheDir`	缓存目录	`string`	`.vitepress/cache`
`cleanUrls`	是否删除 URL 中的 `.html` 扩展名	`boolean`	`false`
`ignoreDeadLinks`	是否忽略死链接	`boolean \| 'localhostLinks' \| 'localhostLinks'[]`	`false`
`rewrites`	路径重写映射	`Record<string, string>`	-
`sitemap`	Sitemap 配置	`SitemapConfig \| false`	-
`mpa`	是否在 MPA 模式下构建	`boolean`	`false`
`appearance`	是否启用深色模式	`boolean \| 'dark' \| 'force-dark' \| UseDarkOptions`	`true`
`lastUpdated`	是否使用 Git 获取每个页面的最后更新时间戳	`boolean`	`false`
`markdown`	Markdown 解析器选项配置	`MarkdownOption`	-
`vite`	Vite 配置选项	`import('vite').UserConfig`	-
`vue`	Vue 插件选项	`import('@vitejs/plugin-vue').Options`	-
`buildEnd`	构建完成后的钩子函数	`(siteConfig: SiteConfig) => Awaitable<void>`	-
`postRender`	SSG 渲染完成时的钩子函数	`(context: SSGContext) => Awaitable<SSGContext \| void>`	-
`transformHead`	在生成每个页面之前转换 head 的钩子函数	`(context: TransformContext) => Awaitable<HeadConfig[]>`	-
`transformHtml`	在保存到磁盘之前转换每个页面内容的钩子函数	`(code: string, id: string, context: TransformContext) => Awaitable<string \| void>`	-
`transformPageData`	转换每个页面的 pageData 的钩子函数	`(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> \| { [key: string]: any } \| void>`	-

站点元数据

title

站点的标题。使用默认主题时，这将显示在导航栏中。每个页面可以通过 frontmatter 覆盖。

它还将用作所有单独页面标题的默认后缀，除非定义了 titleTemplate。单个页面的最终标题将是其第一个 <h1> 标题的文本内容加上的全局 title。

typescript

export default {
  title: 'My Awesome Site'
}

titleTemplate

允许自定义每个页面的标题后缀或整个标题。每个页面可以通过 frontmatter 覆盖。

typescript

export default {
  title: 'My Awesome Site',
  titleTemplate: 'Custom Suffix'
}

要完全自定义标题的呈现方式，可以在 titleTemplate 中使用 :title 标识符：

typescript

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

该选项可以设置为 false 以禁用标题后缀。

description

站点的描述。这将呈现为页面 HTML 中的 <meta> 标签。每个页面可以通过 frontmatter 覆盖。

typescript

export default {
  description: 'A VitePress site'
}

head

要在页面 HTML 的 <head> 标签中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。可以通过 frontmatter 为每个页面追加。

类型定义：

typescript

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

示例：添加一个图标

typescript

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
}

示例：添加谷歌字体

typescript

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' }
    ]
  ]
}

路由

base

站点将部署的 base URL。它应始终以斜杠开头和结尾。

typescript

export default {
  base: '/base/'
}

cleanUrls

是否删除 URL 中的 .html 扩展名。

typescript

export default {
  cleanUrls: true
}

rewrites

路径重写映射，允许将路径映射到其他路径。

typescript

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

构建

outDir

构建输出目录。

typescript

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

assetsDir

静态资源目录。

typescript

export default {
  assetsDir: 'assets'
}

srcDir

typescript

export default {
  srcDir: './src'
}

publicDir

公共目录的位置。

typescript

export default {
  publicDir: './public'
}

cacheDir

缓存目录。

typescript

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

ignoreDeadLinks

是否忽略死链接。可以设置为：

true：忽略所有死链接
'localhostLinks'：仅忽略 localhost 链接
['localhostLinks', '...']：忽略指定的链接类型

typescript

export default {
  ignoreDeadLinks: true
}

sitemap

Sitemap 配置。

typescript

export default {
  sitemap: {
    hostname: 'https://example.com'
  }
}

mpa

设置为 true 时，生产应用程序将在 MPA 模式下构建。MPA 模式默认提供零 JavaScript 支持，代价是禁用客户端导航，并且需要明确选择加入才能进行交互。

typescript

export default {
  mpa: true
}

主题

appearance

是否启用深色模式（通过将 .dark 类添加到 <html> 元素）。

如果该选项设置为 true，则默认主题将由用户的首选配色方案决定
如果该选项设置为 dark，则默认情况下主题将是深色的，除非用户手动切换它
如果该选项设置为 false，用户将无法切换主题

typescript

export default {
  appearance: true
}

lastUpdated

是否使用 Git 获取每个页面的最后更新时间戳。时间戳将包含在每个页面的页面数据中，可通过 useData 访问。

使用默认主题时，启用此选项将显示每个页面的最后更新时间。可以通过 themeConfig.lastUpdatedText 选项自定义文本。

typescript

export default {
  lastUpdated: true
}

自定义

markdown

配置 Markdown 解析器选项。VitePress 使用 Markdown-it 作为解析器，使用 Shiki 来高亮不同语言语法。

typescript

export default {
  markdown: {
    // Markdown 配置选项
  }
}

vite

将原始 Vite 配置传递给内部 Vite 开发服务器 / bundler。

typescript

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

vue

将原始的 @vitejs/plugin-vue 选项传递给内部插件实例。

typescript

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

构建钩子

VitePress 构建钩子允许向站点添加新功能和行为：Sitemap、Search Indexing、PWA、Teleport。

buildEnd

buildEnd 是一个构建 CLI 钩子，它将在构建 SSG 完成后但在 VitePress CLI 进程退出之前运行。

typescript

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

postRender

postRender 是一个构建钩子，在 SSG 渲染完成时调用。它将允许在 SSG 期间处理传递的内容。

typescript

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

类型定义：

typescript

interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead

transformHead 是一个构建钩子，用于在生成每个页面之前转换 head。它将允许添加无法静态添加到 VitePress 配置中的 head entries。

警告： 不要改变 context 中的任何东西。

typescript

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

类型定义：

typescript

interface TransformContext {
  page: string // 例如 index.md (相对于 srcDir)
  assets: string[] // 所有非 js/css 资源均作为完全解析的公共 URL
  siteConfig: SiteConfig
  siteData: SiteData
  pageData: PageData
  title: string
  description: string
  head: HeadConfig[]
  content: string
}

示例：添加 canonical URL

typescript

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

transformHtml 是一个构建钩子，用于在保存到磁盘之前转换每个页面的内容。

警告： 不要改变 context 中的任何东西。另外，修改 html 内容可能会导致运行时出现激活问题。

typescript

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

transformPageData

transformPageData 是一个钩子，用于转换每个页面的 pageData。可以直接改变 pageData 或返回将合并到 PageData 中的更改值。

警告： 不要改变 context 中的任何东西。请注意，这可能会影响开发服务器的性能，特别是当在钩子中有一些网络请求或大量计算时。

typescript

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

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

类型定义：

typescript

interface TransformPageContext {
  siteConfig: SiteConfig
}