站点配置

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

概览

配置解析

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

建议在配置文件中使用 ES 模块语法。配置文件应该默认导出一个对象：

export default {
  // 应用级配置选项
  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({
    // 应用级配置选项
    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。例如：

import { defineConfig } from 'vitepress'

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

export default 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}`
      }))
    ]
  }
})

配置智能提示

使用 defineConfig 辅助函数将为配置选项提供 TypeScript 支持的智能提示。假设 IDE 支持它，那么在 JavaScript 和 TypeScript 中都将触发智能提示。

import { defineConfig } from 'vitepress'

export default 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`
  }
})

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
每个页面可以通过 frontmatter 覆盖

站点的标题。使用默认主题时，这将显示在导航栏中。

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

export default {
  title: 'My Awesome Site'
}

# Hello

页面标题就是 Hello | My Awesome Site.

titleTemplate

类型：string | boolean
每个页面可以通过 frontmatter 覆盖

允许自定义每个页面的标题后缀或整个标题。例如：

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
每个页面可以通过 frontmatter 覆盖

站点的描述。这将呈现为页面 HTML 中的 <meta> 标签。

export default {
  description: 'A VitePress site'
}

head

类型：HeadConfig[]
默认值： []
可以通过 frontmatter 为每个页面追加

要在页面 HTML 的 <head> 标签中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。

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

示例：添加一个图标

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // 将 favicon.ico 放在公共目录中，如果设置了 base，则使用 /base/favicon.ico

/* 渲染成:
  <link rel="icon" href="/favicon.ico">
*/

示例：添加谷歌字体

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

/* 渲染成:
  <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">
*/

示例：添加一个 serviceWorker

export default {
  head: [
    [
      'script',
      { id: 'register-sw' },
      `;(() => {
        if ('serviceWorker' in navigator) {
          navigator.serviceWorker.register('/sw.js')
        }
      })()`
    ]
  ]
}

/* 渲染成:
  <script id="register-sw">
    ;(() => {
      if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
      }
    })()
  </script>
*/

示例：使用谷歌分析

export default {
  head: [
    [
      'script',
      { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
    ],
    [
      'script',
      {},
      `window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'TAG_ID');`
    ]
  ]
}

/* 渲染成:
  <script async src="https://www.googletagmanager.com/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
默认值： /

站点将部署到的 base URL。如果计划在子路径例如 GitHub 页面下部署站点，则需要设置此项。如果计划将站点部署到 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 pattern。

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: [
    // 忽略精确网址 "/playground"
    '/playground',
    // 忽略所有 localhost 链接
    /^https?:\/\/localhost/,
    // 忽略所有包含 "/repl/" 的链接
    /\/repl\//,
    // 自定义函数，忽略所有包含 "ignore "的链接
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

metaChunk experimental

类型：boolean
默认值：false

当设置为 true 时，将页面元数据提取到单独的 JavaScript 块中，而不是内联在初始 HTML 中。这使每个页面的 HTML 负载更小，并使页面元数据可缓存，从而当站点中有很多页面时可以减少服务器带宽。

mpa experimental

类型：boolean
默认值： false

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

主题

appearance

类型：boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions
默认值： true

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

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

此选项注入一个内联脚本，使用 vitepress-theme-appearance key 从本地存储恢复用户设置。这确保在呈现页面之前应用 .dark 类以避免闪烁。

appearance.initialValue 只能是 'dark' | undefined。不支持 Refs 或 getters。

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 开发服务器 / bundler。

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

vue

类型：import('@vitejs/plugin-vue').Options

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

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

构建钩子

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

Sitemap
Search Indexing
PWA
Teleport

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 是一个构建钩子，用于在生成每个页面之前转换 head。它将允许添加无法静态添加到 VitePress 配置中的 head entries。只需要返回额外的 entries，它们将自动与现有 entries 合并。

WARNING

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

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

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
}

请注意，仅在静态生成站点时才会调用此钩子。在开发期间不会调用它。如果需要在开发期间添加动态 head 条目，可以使用 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`
      }
    ])
  }
}

示例：添加 canonical 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 是一个构建钩子，用于在保存到磁盘之前转换每个页面的内容。

WARNING

不要改变 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 中的更改值。

WARNING

不要改变 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)
    }
  }
}

interface TransformPageContext {
  siteConfig: SiteConfig
}

站点配置 ​

概览 ​

配置解析 ​

配置智能提示 ​

主题类型提示 ​

Vite、Vue 和 Markdown 配置 ​

站点元数据 ​

title ​

titleTemplate ​

description ​

head ​

示例：添加一个图标 ​

示例：添加谷歌字体 ​

示例：添加一个 serviceWorker ​

示例：使用谷歌分析 ​

lang ​

base ​

路由 ​

cleanUrls ​

rewrites ​

构建 ​

srcDir ​

srcExclude ​

outDir ​

assetsDir ​

cacheDir ​

ignoreDeadLinks ​

metaChunk experimental ​

mpa experimental ​

主题 ​

appearance ​

lastUpdated ​

自定义 ​

markdown ​

vite ​

vue ​

构建钩子 ​

buildEnd ​

postRender ​

transformHead ​

示例：添加 canonical URL <link> ​

transformHtml ​

transformPageData ​

站点配置

概览

配置解析

配置智能提示

主题类型提示

Vite、Vue 和 Markdown 配置

站点元数据

title

titleTemplate

description

head

示例：添加一个图标

示例：添加谷歌字体

示例：添加一个 serviceWorker

示例：使用谷歌分析

lang

base

路由

cleanUrls

rewrites

构建

srcDir

srcExclude

outDir

assetsDir

cacheDir

ignoreDeadLinks

metaChunk experimental

mpa experimental

主题

appearance

lastUpdated

自定义

markdown

vite

vue

构建钩子

buildEnd

postRender

transformHead

示例：添加 canonical URL `<link>`

transformHtml

transformPageData