17 KiB

Raw Blame History Unescape Escape

outline
deep

站点配置

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

概览

配置解析

配置文件总是从 <root>/.vitepress/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 Config

Vite

你可以使用 VitePress 配置中的 vite 选项配置底层 Vite 实例。无需创建单独的 Vite 配置文件。
Vue

VitePress 已经包含 Vite 的官方 Vue 插件（@vitejs/plugin-vue）。你可以配置 VitePress 中的 vue 选项。
Markdown

你可以使用 VitePress 配置中的 markdown 选项配置底层的 Markdown-It 实例。

站点元数据

标题

key title
Type: string
Default: VitePress
每个页面可以通过 frontmatter 覆写

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

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

export default {
	title: 'My Awesome Site',
}

# Hello

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

标题模板

key: titleTemplate
Type: 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 以禁用标题后缀。

描述

key: description
Type: string
Default: A VitePress site
每个页面可以通过 frontmatter 覆写

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

export default {
	description: 'A VitePress site',
}

head

key: head
Type: HeadConfig[]
Default: []
每个页面可以通过 frontmatter 添加

::: details 要在页面 HTML 的 <head> 标记中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。 Additional elements to render in the <head> tag in the page HTML. The user-added tags are rendered before the closing head tag, after VitePress tags. :::

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]

语言

key: lang
Type: string
Default: en-US

站点的 lang 属性。这将呈现为页面 HTML 中的 <html lang="en-US"> 标签。

export default {
	lang: 'en-US',
}

base

key: base
Type: string
Default: /

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

base 会自动添加到其他选项中以 / 开头的所有 URL 前面，因此你只需指定一次。

export default {
	base: '/base/',
}

路由

简洁 URL

key: cleanUrls
Type: boolean
Default: false

当设置为 true 时，VitePress 将从 URL 中删除 .html 后缀。另请参阅生成简洁的 URL。

::: warning 需要服务器支持要启用此功能，可能需要在你的托管平台上进行额外配置。要使其正常工作，你的服务器必须能够在不重定向的情况下访问 /foo 时提供 /foo.html。 :::

路由重写

key: rewrites
Type: Record<string, string>

自定义目录 <-> URL 映射。详细信息请参阅路由：路由重写。

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

Build

srcDir

key: srcDir
Type: string
Default: .

markdown 页面的目录，相对于项目根目录。另请参阅根目录和源目录。

export default {
	srcDir: './src',
}

srcExclude

key: srcExclude
Type: string
Default: undefined

::: details 用于匹配应作为源内容输出的 markdown 文件的全局模式。 A glob pattern for matching markdown files that should be excluded as source content. :::

export default {
	srcExclude: ['**/README.md', '**/TODO.md'],
}

outDir

key: outDir
Type: string
Default: ./.vitepress/dist

项目的构建输出位置，相对于项目根目录。

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

cacheDir

key: cacheDir
Type: string
Default: ./.vitepress/cache

缓存文件的目录，相对于项目根目录。另请参阅：vite: cacheDir。

export default {
	cacheDir: './.vitepress/.vite',
}

忽略死链

key: ignoreDeadLinks
Type: boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]
Default: 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')
		},
	],
}

多页应用

key: mpa
Type: boolean
Default: false

::: details 设置为 true 时，生产应用程序将在 MPA 模式下构建。MPA 模式默认提供零 JavaScript 支持，代价是禁用客户端导航，并且需要明确选择加入才能进行交互。 When set to true, the production app will be built in MPA Mode. MPA mode ships 0kb JavaScript by default, at the cost of disabling client-side navigation and requires explicit opt-in for interactivity. :::

主题

外观

key: appearance
Type: boolean | 'dark'
Default: true

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

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

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

定制

markdown

key: markdown
Type: 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

key: vite
Type: import('vite').UserConfig

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

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

vue

key: vue
Type: import('@vitejs/plugin-vue').Options

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

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

构建钩子

VitePress build hooks allow you to add new functionality and behaviors to your website: VitePress 构建钩子允许你向你的网站添加新功能和行为：

Sitemap 网站地图
Search Indexing 搜索索引
PWA 渐进式网页应用
Teleports 传送门

buildEnd

key: buildEnd
Type: (siteConfig: SiteConfig) => Awaitable<void>

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

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

postRender

key: postRender
Type: (context: SSGContext) => Awaitable<SSGContext | void>

::: details postRender 是一个构建钩子，在 SSG 渲染完成时调用。它将允许你在 SSG(静态站点生成) 期间处理传递的内容。 postRender is a build hook, called when SSG rendering is done. It will allow you to handle the teleports content during SSG. :::

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

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

transformHead

key: transformHead
Type: (context: TransformContext) => Awaitable<HeadConfig[]>

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

::: 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

key: transformHtml
Type: (code: string, id: string, ctx: TransformContext) => Awaitable<string | void>

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

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

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

transformPageData

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

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