站点配置

站点配置是您可以定义站点的全局设置的地方。App config选项定义应用于每个VitePress站点的设置，而不管它使用的是什么主题。例如，基本目录或站点标题。

概述

配置示例

配置文件始终从<root>/.vitpress/config.[ext]解析，其中<root>是vitepress项目的根目录，[ext]是支持的文件扩展名之一。支持开箱即用的TypeScript。支持的扩展包括.js、.ts、.cjs、.mjs、.cts和.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实例。

站点的元数据

标题

类型： string
默认值： VitePress
通过Frontmatter可以覆盖每页

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

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

export default {
  title: 'My Awesome Site'
}

# Hello

页面的标题将是Hello | My Awesome Site。

标题模板（titleTemplate）

类型： string
通过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以禁用标题后缀。

描述

类型：string
默认值：`A VitePress site
可通过frontmatter覆盖每页站点的说明。这将在页面HTML中呈现为＜meta＞标记。

export default {
  description: 'A VitePress site'
}

head

类型：HeadConfig[]
默认值：[]
可通过frontmatter覆盖每页

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

export default {
  head: [
    [
      'link',
      { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
      // would render:
      //
      // <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    ],

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

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

lang

类型: string
默认值: en-US 站点的语言属性。这将在页面html中呈现为<html lang=“en-US”>标记。

export default {
  lang: 'en-US'
}

base

类型： string
默认值： /

网站将部署在base URL。如果您计划在子路径（例如GitHub页面）下部署网站，则需要设置此base值。

如果您计划将站点部署到https://foo.github.io/bar/，则应将base设置为“/bar/”。它应该始终以斜线开头和结尾。

在其他选项中，所有以/开头的URL都会自动加上base值，因此只需指定一次。

export default {
  base: '/base/'
}

路由

cleanUrls

类型：boolean
默认值：false

当设置为true时，VitePress将从URL中删除尾随的.html。另请参阅 Generating Clean 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'
}

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 experimental

类型: boolean
默认值: false

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

主题

外观

类型： boolean | dark
默认值： true

是否启用“暗色”模式 (通过将.dark类添加到＜html＞元素)

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

它还注入了内联脚本，该脚本尝试通过vitepress-theme-appearances键从本地存储读取用户设置，并恢复用户首选的颜色模式。这样可以确保在渲染页面之前应用.dark类，以避免闪烁。

export default {
  appearance: true
}

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,
      
    // adjust how header anchors are generated,
    // useful for integrating with tools that use different conventions
    anchors: {
      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 dev服务器/bundler。

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

vue

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

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

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

Build Hooks

Sitemap
Serach 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

Don't mutate anything inside the 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

Don't mutate anything inside the ctx. Also, modifying the html content may cause hydration problems in runtime.

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

transformPageData

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

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

WARNING

Don't mutate anything inside the 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 配置 ​

站点的元数据 ​

标题 ​

标题模板（titleTemplate） ​

描述 ​

head ​

lang ​

base ​

路由 ​

cleanUrls ​

rewrites ​

构建 ​

srcDir ​

srcExclude ​

outDir ​

cacheDir ​

ignoreDeadLinks ​

mpa experimental ​

主题 ​

外观 ​

lastUpdated ​

定制 ​

markdown ​

vite ​

vue ​

Build Hooks ​

buildEnd ​

postRender ​

transformHead ​

transformHtml ​

transformPageData ​

站点配置

概述

配置示例

配置智能感知

典型主题配置

Vite, Vue & Markdown 配置

站点的元数据

标题

标题模板（titleTemplate）

描述

head

lang

base

路由

cleanUrls

rewrites

构建

srcDir

srcExclude

outDir

cacheDir

ignoreDeadLinks

mpa experimental

主题

外观

lastUpdated

定制

markdown

vite

vue

Build Hooks

buildEnd

postRender

transformHead

transformHtml

transformPageData