站点配置

站点配置是您可以定义站点的全局设置的位置。应用程序配置选项定义适用于每个 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.',
  ...
}

配置智能感知

使用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
可以通过页面的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]

示例: 添加 favicon

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // put favicon.ico in public directory, if base is set, use /base/favicon.ico

/* 渲染结果:
  <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' }
    ]
  ]
}

/* 渲染结果:
  <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')
        }
      })()`
    ]
  ]
}

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

示例: 使用 Google Analytics

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
默认: /

站点将部署到的基本 URL。如果您计划在子路径（例如 GitHub 页面）下部署站点，则需要设置此项。如果您计划将站点部署到https://foo.github.io/bar/，那么您应该将 base 设置为'/bar/'。它应该始终以斜线开头和结尾。

基数会自动添加到其他选项中以 / 开头的所有 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

用于存放资源文件的目录。另请参阅：assetsDir。

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

mpa 实验性

类型: boolean
默认: false

当设置为true时，生产应用程序将以 MPA 模式构建。 MPA 模式默认提供 0kb JavaScript，但代价是禁用客户端导航，并且需要显式选择加入交互性。

主题

appearance

类型: boolean | 'dark'
默认: true

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

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

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

lastUpdated

类型: boolean
默认: false

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

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

定制

markdown

类型: MarkdownOption

配置 Markdown 解析器选项。 VitePress 使用 Markdown-it 作为解析器，并使用 Shiki 来突出显示语言语法。在此选项中，您可以传递各种 Markdown 相关选项来满足您的需求。

export default {
  markdown: {
    theme: 'material-theme-palenight',
    lineNumbers: true,

    // adjust how header anchors are generated,
    // useful for integrating with tools that use different conventions
    anchor: {
      slugify(str) {
        return encodeURIComponent(str)
      }
    }
  }
}

以下是该对象中可以拥有的所有选项：

interface MarkdownOptions extends MarkdownIt.Options {
  // Custom theme for syntax highlighting.
  // You can use an existing theme.
  // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes
  // Or add your own theme.
  // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme
  theme?:
    | Shiki.IThemeRegistration
    | { light: Shiki.IThemeRegistration; dark: Shiki.IThemeRegistration }

  // Enable line numbers in code block.
  lineNumbers?: boolean

  // Add support for your own languages.
  // https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki
  languages?: Shiki.ILanguageRegistration

  // markdown-it-anchor plugin options.
  // See: https://github.com/valeriangalliat/markdown-it-anchor#usage
  anchor?: anchorPlugin.AnchorOptions

  // markdown-it-attrs plugin options.
  // See: https://github.com/arve0/markdown-it-attrs
  attrs?: {
    leftDelimiter?: string
    rightDelimiter?: string
    allowedAttributes?: string[]
    disable?: boolean
  }

  // specify default language for syntax highlighter
  defaultHighlightLang?: string

  // @mdit-vue/plugin-frontmatter plugin options.
  // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-frontmatter#options
  frontmatter?: FrontmatterPluginOptions

  // @mdit-vue/plugin-headers plugin options.
  // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers#options
  headers?: HeadersPluginOptions

  // @mdit-vue/plugin-sfc plugin options.
  // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc#options
  sfc?: SfcPluginOptions

  // @mdit-vue/plugin-toc plugin options.
  // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
  toc?: TocPluginOptions

  // Configure the Markdown-it instance.
  config?: (md: MarkdownIt) => void
}

vite

类型: import('vite').UserConfig

将原始 Vite Config 传递到内部 Vite 开发服务器/捆绑器。

export default {
  vite: {
    // Vite config options
  }
}

vue

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

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

export default {
  vue: {
    // @vitejs/plugin-vue options
  }
}

构建钩子

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

Sitemap
Search Indexing
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 期间处理传送内容。

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

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

transformHead

类型: (context: TransformContext) => Awaitable<HeadConfig[]>

transformHead 是一个构建钩子，用于在生成每个页面之前转换头部。它将允许您添加无法静态添加到 VitePress 配置中的头条目。您只需返回额外的条目，它们将自动与现有条目合并。

WARNING

不要改变 ctx 内的任何内容。

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
}

transformHtml

类型: (code: string, id: string, ctx: TransformContext) => Awaitable<string | void>

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

WARNING

不要改变 ctx 内的任何内容。另外，修改html内容可能会导致运行时水合问题。

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

transformPageData

类型: (pageData: PageData, ctx: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>

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

WARNING

不要改变 ctx 内的任何内容。

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
}

站点配置 ​

概述 ​

配置解析 ​

配置智能感知 ​

类型化主题配置 ​

Vite、Vue 和 Markdown 配置 ​

站点元数据 ​

title ​

titleTemplate ​

description ​

head ​

示例: 添加 favicon ​

示例: 添加 Google Fonts ​

示例: 注册 service worker ​

示例: 使用 Google Analytics ​

lang ​

base ​

路由 ​

cleanUrls ​

rewrites ​

构建 ​

srcDir ​

srcExclude ​

outDir ​

assetsDir ​

cacheDir ​

ignoreDeadLinks ​

mpa 实验性 ​

主题 ​

appearance ​

lastUpdated ​

定制 ​

markdown ​

vite ​

vue ​

构建钩子 ​

buildEnd ​

postRender ​

transformHead ​

transformHtml ​

transformPageData ​

站点配置

概述

配置解析

配置智能感知

类型化主题配置

Vite、Vue 和 Markdown 配置

站点元数据

title

titleTemplate

description

head

示例: 添加 favicon

示例: 添加 Google Fonts

示例: 注册 service worker

示例: 使用 Google Analytics

lang

base

路由

cleanUrls

rewrites

构建

srcDir

srcExclude

outDir

assetsDir

cacheDir

ignoreDeadLinks

mpa 实验性

主题

appearance

lastUpdated

定制

markdown

vite

vue

构建钩子

buildEnd

postRender

transformHead

transformHtml

transformPageData