-
-
-```
-
-## ``
-
-`` 组件只在客户端渲染它的插槽。
-
-由于 VitePress 应用在生成静态文件之后会在 Node.js 中进行服务端渲染，因此任何 Vue 的使用都必须符合通用代码的要求。简而言之，确保只在 beforeMount 或 mounted 钩子中访问浏览器以及 DOM API。
-
-如果你正在使用不支持 SSR 的组件 (例如，包含自定义指令)，你可以将它们包装在 `ClientOnly` 组件中。
-
-```vue-html
-
-
-
-```
diff --git a/docs/zh/config/app-config.md b/docs/zh/config/app-config.md
deleted file mode 100644
index f3718abb..00000000
--- a/docs/zh/config/app-config.md
+++ /dev/null
@@ -1,393 +0,0 @@
-# 应用全局配置 {#app-config}
-
-应用全局配置是定义站点的全局配置的地方。应用全局配置不仅限于主题配置，还有如“根目录”的配置，或站点的“标题”设置。
-
-```ts
-export default {
- // These are app level configs.
- lang: 'en-US',
- title: 'VitePress',
- description: 'Vite & Vue powered static site generator.',
- ...
-}
-```
-
-## appearance
-
-- 类型：`boolean | 'dark'`
-- 默认值：`true`
-
-这个配置项可以配置是否开启“黑暗”模式。
-
-- 如果选项设置为 `true`，默认的主题将由用户的首选的颜色方案来决定。
-- 如果选项设置为 `dark`，该主题将默认为深色，用户手动切换颜色才会发生改变。
-- 如果选项设置为 `false`，用户将无法切换主题。
-
-它还注入了内联脚本，通过 `vitepress-theme-appearance` 键从本地存储中读取用户设置，并恢复用户偏好的颜色模式。
-
-```ts
-export default {
- appearance: true
-}
-```
-
-## base
-
-- 类型：`string`
-- 默认值：`/`
-
-站点将被部署到的根 URL。如果你打算在一个子路径下部署你的站点，例如 GitHub 页面，你就需要进行配置。如果你计划将站点部署到 `https://foo.github.io/bar/`，那么你应该将 base 设置为 `'/bar/'`。它应该总是以斜线开始，以斜线结束。
-
-base 会自动预置到其他选项中以/开头的所有 URL 中，所以你只需要指定一次。
-
-```ts
-export default {
- base: '/base/'
-}
-```
-
-## description
-
-- 类型：`string`
-- 默认值：`A VitePress site`
-
-站点的描述。在 HTML 页面中将被渲染成 `` 标签。
-
-```ts
-export default {
- description: 'A VitePress site'
-}
-```
-
-## head
-
-- 类型：`HeadConfig[]`
-- 默认值：`[]`
-
-在 HTML 页面的 `` 标签中呈现的额外元素。用户添加的标签将在 `head` 标签结束前呈现，在 VitePress 标签之后。
-
-```ts
-export default {
- head: [
- [
- 'link',
- { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
- ]
- // would render:
- ]
-}
-```
-
-```ts
-type HeadConfig =
- | [string, Record]
- | [string, Record, string]
-```
-
-## ignoreDeadLinks
-
-- 类型：`boolean | 'localhostLinks'`
-- 默认值：`false`
-
-当将其设置为 `true` 时，VitePress 不会因为死链接构建失败。若将其设置为 `localhostLinks`，`localhost` 链接不会构建失败，其他的死链接仍然会使构建失败。
-
-```ts
-export default {
- ignoreDeadLinks: true
-}
-```
-
-## lang
-
-- 类型：`string`
-- 默认值：`en-US`
-
-站点的语言属性。在 HTML 页面中将被渲染为 `` 标签。
-
-```ts
-export default {
- lang: 'en-US'
-}
-```
-
-## lastUpdated
-
-- 类型：`boolean`
-- 默认值：`false`
-
-使用 git commit 来获取时间戳。该选项使默认主题显示页面的最后更新时间。你可以通过 [`themeConfig.lastUpdatedText`](theme-config#lastupdatedtext) 选项来自定义文本。
-
-```ts
-export default {
- lastUpdated: true
-}
-```
-
-## markdown
-
-- 类型：`MarkdownOption`
-
-配置 Markdown 解析器的选项。VitePress 使用 [Markdown-it](https://github.com/markdown-it/markdown-it) 作为解析器，并使用 [Shiki](https://shiki.matsu.io/) 来高亮语言的语法。在这个选项中，你可以通过各种与 Markdown 有关的选项来满足你的需要。
-
-```js
-export default {
- markdown: {
- theme: 'material-palenight',
- lineNumbers: true
- }
-}
-```
-
-以下是你在这个对象中可以进行设置的所有选项：
-
-```ts
-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
-}
-```
-
-## outDir
-
-- 类型：`string`
-- 默认值：`./.vitepress/dist`
-
-站点的构建输出位置，相对于项目根目录。(比如相对于 `docs` 目录，如果你运行的是 `vitepress build docs`)。
-
-```ts
-export default {
- outDir: '../public'
-}
-```
-
-## cacheDir
-
-- 类型：`string`
-- 默认值：`./.vitepress/cache`
-
-缓存文件的目录，相对于项目根目录。(比如相对于 `docs` 目录，如果你运行的是 `vitepress build docs`)。参见：[cacheDir](https://cn.vitejs.dev/config/shared-options.html#cachedir)。
-
-```ts
-export default {
- cacheDir: './.vitepress/.vite'
-}
-```
-
-## srcDir
-
-- 类型：`string`
-- 默认值：`.`
-
-存储 markdown 文件的位置，相对于项目根目录。
-
-```ts
-export default {
- srcDir: './src'
-}
-```
-
-## title
-
-- 类型：`string`
-- 默认值：`VitePress`
-
-站点的标题。这将显示在导航栏中。除非定义了 `titleTemplate`，否则也作为所有页面标题的后缀。
-
-```ts
-export default {
- title: 'VitePress'
-}
-```
-
-## titleTemplate
-
-- 类型：`string | boolean`
-
-标题的后缀。例如，如果你将 `title` 设置为 `VitePress`，并将 `titleTemplate` 设置为 `My Site`，那么html 标题就变成 `VitePress | My Site`。
-
-设置为 `false` 表示禁用该功能。如果该选项是 `undefined`，那么将使用 `title` 选项的值。
-
-```ts
-export default {
- title: 'VitePress',
- titleTemplate: 'Vite & Vue powered static site generator'
-}
-```
-
-要配置 `|` 以外的标题分隔符，你可以省略 `title`，在 `titleTemplate` 中使用 `:title` 符号。
-
-```ts
-export default {
- titleTemplate: ':title - Vitepress'
-}
-```
-
-## cleanUrls {#cleanurls}
-
-- 类型：`boolean`
-- 默认值：`false`
-
-允许从 URL 中去除尾部的 `.html`，并可选择生成简洁的目录结构。
-
-```ts
-export default {
- cleanUrls: true
-}
-```
-
-::: warning
-启用此功能可能需要在你的托管平台上进行额外配置。为了使其正常工作，你的服务器必须**在不重定向的情况下**，请求 `/foo` 时提供 `/foo.html` 。
-:::
-
-## rewrites
-
-- Type: `Record`
-
-定义自定义目录和 URL 的映射。有关详细信息，请参阅[路由：自定义映射](/guide/routing#customize-the-mappings)。
-
-```ts
-export default {
- rewrites: {
- 'source/:page': 'destination/:page'
- }
-}
-```
-
-## 构建钩子 {#build-hooks}
-
-VitePress 构建钩子允许你向你的网站添加新的功能和行为：
-
-- Sitemap
-- Search Indexing
-- PWA
-
-### transformHead
-
-- 类型：`(ctx: TransformContext) => Awaitable`
-
-`transformHead` 是一个构建钩子，用于在生成每个页面之前转换 head。它将允许你添加不能静态添加到你的VitePress 配置中的 head 选项。你只需要返回额外的选项，它们将被自动合并到现有的选项中。
-
-::: warning
-不要改变 `ctx` 中的任何东西。
-:::
-
-```ts
-export default {
- async transformHead(ctx) {
- // ...
- }
-}
-```
-
-```ts
-interface TransformContext {
- siteConfig: SiteConfig
- siteData: SiteData
- pageData: PageData
- title: string
- description: string
- head: HeadConfig[]
- content: string
-}
-```
-
-### transformHtml
-
-- 类型：`(code: string, id: string, ctx: TransformContext) => Awaitable`
-
-`transformHtml` 是一个构建钩子，用于在保存到磁盘之前转换每个页面的内容。
-
-::: warning
-不要改变 `ctx` 中的任何东西。另外，修改 html 内容可能会在运行时引起激活问题。
-:::
-
-```ts
-export default {
- async transformHtml(code, id, context) {
- // ...
- }
-}
-```
-
-### transformPageData
-
-- 类型：`(pageData: PageData) => Awaitable | { [key: string]: any } | void>`
-
-`transformPageData` 是一个用于转换每个页面的 `pageData` 的钩子。你可以直接改变 `pageData` 或者返回改变的值，这些值将被合并到 PageData 中。
-
-```ts
-export default {
- async transformPageData(pageData) {
- pageData.contributors = await getPageContributors(pageData.relativePath)
- }
-
- // or return data to be merged
- async transformPageData(pageData) {
- return {
- contributors: await getPageContributors(pageData.relativePath)
- }
- }
-}
-```
-
-### buildEnd
-
-- 类型：`(siteConfig: SiteConfig) => Awaitable`
-
-`buildEnd` 是一个构建 CLI 的钩子，它将在构建 (SSG) 完成后，VitePress CLI 进程退出前运行。
-
-```ts
-export default {
- async buildEnd(siteConfig) {
- // ...
- }
-}
-```
diff --git a/docs/zh/config/frontmatter-config.md b/docs/zh/config/frontmatter-config.md
deleted file mode 100644
index 9d38f5fd..00000000
--- a/docs/zh/config/frontmatter-config.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# Frontmatter 配置 {#frontmatter-config}
-
-Frontmatter 支持基于页面的配置。在每个标签上，你可以自由地添加任何设置来覆盖任何全局应用或主题配置。此外，还有一些配置，你只能在 Frontmatter 中定义。
-
-```yaml
----
-title: Docs with VitePress
-editLink: true
----
-```
-
-你可以通过 `$frontmatter` 在任何 markdown 文件中访问 frontmatter。
-
-```md
-{{ $frontmatter.title }}
-```
-
-## title
-
-- Type: `string`
-
-页面的标题。它与 [config.title](../config/app-config#title) 相同，并覆盖了应用全局配置。
-
-```yaml
----
-title: VitePress
----
-```
-
-## titleTemplate
-
-- Type: `string | boolean`
-
-标题的后缀。它与 [config.titleTemplate](../config/app-config#titletemplate) 相同，并覆盖了应用全局配置。
-
-```yaml
----
-title: VitePress
-titleTemplate: Vite & Vue powered static site generator
----
-```
-
-## description
-
-- Type: `string`
-
-页面的描述。它与 [config.description](../config/app-config#description) 相同，并覆盖了应用全局配置。
-
-```yaml
----
-description: VitePress
----
-```
-
-## head
-
-- Type: `HeadConfig[]`
-
-指定要注入的额外 head 标签。
-
-```yaml
----
-head:
- - - meta
- - name: description
- content: hello
- - - meta
- - name: keywords
- content: super duper SEO
----
-```
-
-```ts
-type HeadConfig =
- | [string, Record]
- | [string, Record, string]
-```
-
-## lastUpdated
-
-- Type: `boolean`
-- Default: `true`
-
-在当前页面是否显示[最后更新](../guide/theme-last-updated)文本。
-
-```yaml
----
-lastUpdated: false
----
-```
-
-## layout
-
-- Type: `doc | home | page`
-- Default: `doc`
-
-决定页面的布局。
-
-- `doc` - It applies default documentation styles to the markdown content.
-- `home` - Special layout for "Home Page". You may add extra options such as `hero` and `features` to rapidly create beautiful landing page.
-- `page` - Behave similar to `doc` but it applies no styles to the content. Useful when you want to create a fully custom page.
-
-```yaml
----
-layout: doc
----
-```
-
-## hero
-
-- Type: `Hero`
-
-This option only takes effect when `layout` is set to `home`.
-
-It defines contents of home hero section.
-
-```yaml
----
-layout: home
-
-hero:
- name: VitePress
- text: Vite & Vue powered static site generator.
- tagline: Lorem ipsum...
- actions:
- - theme: brand
- text: Get Started
- link: /guide/what-is-vitepress
- - theme: alt
- text: View on GitHub
- link: https://github.com/vuejs/vitepress
----
-```
-
-```ts
-interface Hero {
- // The string shown top of `text`. Comes with brand color
- // and expected to be short, such as product name.
- name?: string
-
- // The main text for the hero section. This will be defined
- // as `h1` tag.
- text: string
-
- // Tagline displayed below `text`.
- tagline?: string
-
- // Action buttons to display in home hero section.
- actions?: HeroAction[]
-}
-
-interface HeroAction {
- // Color theme of the button. Defaults to `brand`.
- theme?: 'brand' | 'alt'
-
- // Label of the button.
- text: string
-
- // Destination link of the button.
- link: string
-}
-```
-
-## features
-
-- Type: `Feature[]`
-
-This option only takes effect when `layout` is set to `home`.
-
-It defines items to display in features section.
-
-You may learn more about it in [Theme: Home Page](../guide/theme-home-page).
-
-## aside
-
-- Type: `boolean`
-- Default: `true`
-
-If you want the right aside component in `doc` layout not to be shown, set this option to `false`.
-
-```yaml
----
-aside: false
----
-```
-
-## outline
-
-- Type: `number | [number, number] | 'deep' | false`
-- Default: `2`
-
-The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](../config/theme-config#outline), and it overrides the theme config.
diff --git a/docs/zh/config/introduction.md b/docs/zh/config/introduction.md
deleted file mode 100644
index 9ee0f3ec..00000000
--- a/docs/zh/config/introduction.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# 简介 {#introduction}
-
-将配置文件放在 `.vitepress/config.js` 中。 这是放置所有 VitePress 特定文件的地方。
-
-```
-.
-├─ docs
-│ ├─ .vitepress
-│ │ └─ config.js
-│ └─ index.md
-└─ package.json
-```
-
-::: tip 提示
-你也可以使用任意的 `.ts`、`.cjs`、`.mjs`、`.cts` 和 `.mts` 作为配置文件的扩展名。
-:::
-
-VitePress 带有 2 种类型的配置。一种是[应用全局配置](./app-config)，它配置站点的基本功能，例如设置站点的标题，或自定义 Markdown 解析器的工作方式。其次是[主题配置](./theme-config)，用于配置站点的主题，例如添加侧边栏，或者添加“在 GitHub 上编辑此页面”链接等功能。
-
-你还可以在 [Frontmatter](./frontmatter-config) 中进行另一种配置。Frontmatter 配置可以覆盖在该特定页面的应用全局配置或主题配置上定义的全局配置。但是，有几个选项也仅在 frontmatter 中可用。
-
-请参阅相应的配置页面以了解更多信息。
-
-## 配置智能提示 {#config-intellisense}
-
-由于 VitePress 附带 TypeScript 类型，你可以利用 IDE 的智能提示和 jsdoc 类型提示：
-
-```js
-/**
- * @type {import('vitepress').UserConfig}
- */
-const config = {
- // ...
-}
-
-export default config
-```
-
-或者，你可以使用 `defineConfig` 辅助函数，它会提供智能提示，而无需 jsdoc 注释：
-
-```js
-import { defineConfig } from 'vitepress'
-
-export default defineConfig({
- // ...
-})
-```
-
-VitePress 也直接支持 TS 配置文件。 你也可以将 `.vitepress/config.ts` 与 `defineConfig` 辅助函数一起使用。
-
-## 主题配置类型 {#typed-theme-config}
-
-默认情况下，`defineConfig` 辅助函数使用默认主题的主题配置类型：
-
-```ts
-import { defineConfig } from 'vitepress'
-
-export default defineConfig({
- themeConfig: {
- // Type is `DefaultTheme.Config`
- }
-})
-```
-
-如果你使用自定义主题并希望对主题配置进行类型检查，则需要使用 `defineConfigWithTheme`，并通过通用参数传递自定义主题的配置类型：
-
-```ts
-import { defineConfigWithTheme } from 'vitepress'
-import { ThemeConfig } from 'your-theme'
-
-export default defineConfigWithTheme({
- themeConfig: {
- // Type is `ThemeConfig`
- }
-})
-```
diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md
index a571d5bd..c1f46675 100644
--- a/docs/zh/guide/asset-handling.md
+++ b/docs/zh/guide/asset-handling.md
@@ -1,46 +1,51 @@
-# 资源处理 {#asset-handling}
+# Asset Handling
-所有的 Markdown 文件都编译成 Vue 组件并由 [Vite](https://github.com/vitejs/vite) 处理。你可以**并且应该**使用相对路径引用资源：
+All Markdown files are compiled into Vue components and processed by [Vite](https://vitejs.dev/guide/assets.html). You can, **and should**, reference any assets using relative URLs:
```md
-
+
```
-你可以在 markdown 文件、主题中的 `*.vue` 组件、styles 里和纯 `.css` 文件中通过使用绝对路径 (基于项目根目录) 或相对路径 (基于你的文件系统) 引用静态资源。相对路径的方式类似于使用 `vue-cli` 或 webpack 的 `file-loader` 时所习惯的写法。
+You can reference static assets in your markdown files, your `*.vue` components in the theme, styles and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's `file-loader`.
-常规的图片、媒体和字体文件类型会被自动检测为静态资源。
+Common image, media, and font filetypes are detected and included as assets automatically.
-所有引用的资源，包括使用绝对路径的资源，都将被复制到 dist 文件夹中，并在生产打包后生成哈希文件名。但不会复制未引用的资源。与 `vue-cli` 一样，小于 4kb 的图片资源将编译成 base64 的内联样式。
+All referenced assets, including those using absolute paths, will be copied to the dist folder with a hashed file name in the production build. Never-referenced assets will not be copied. Image assets smaller than 4kb will be base64 inlined - this can be configured via the [`vite`](/reference/site-config#vite) config option.
-所有资源路径的引用，包括绝对路径，都应基于你的工作目录结构。
+All **static** path references, including absolute paths, should be based on your working directory structure.
-## Public 文件 {#public-files}
+## Public Files
-有时你可能需要提供一些 Markdown 或主题组件中未直接引用的静态资源 (例如，站点图标和 PWA 图标)。 项目根目录下的 `public` 目录 (如果你正在运行的是 `vitepress build docs`，则为 `docs` 文件夹) 将会保留，用以提供源代码中从未引用的静态资源 (例如 `robots.txt`) 和需要保留完全相同的文件名 (不生成哈希) 的资源。
+Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components (for example, favicons and PWA icons). The `public` directory under project root (`docs` folder if you're running `vitepress build docs`) can be used as an escape hatch to provide static assets that either are never referenced in source code (e.g. `robots.txt`), or must retain the exact same file name (without hashing).
-放在 `public` 中的资源将会直接复制到 dist 的根目录。
+Assets placed in `public` will be copied to the root of the dist directory as-is.
-注意，你应该使用从根目录开始以绝对路径引用放在 `public` 中的文件——例如，`public/icon.png` 在源代码中应始终引用为 `/icon.png`。
+Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
+
+There is one exception to this: if you have an HTML page in `public` and link to it from the main site, the router will yield a 404 by default. To get around this, VitePress provides a `pathname://` protocol which allows you to link to another page in the same domain as if the link is external. Contrast these two links:
+
+- [/pure.html](/pure.html)
+-
## Base URL
-如果你的站点没有部署到根 URL，则需要在 `.vitepress/config.js` 中设置 `base` 选项。 例如，如果你要将站点部署到 `https://foo.github.io/bar/`，那么 `base` 应该设置为 `'/bar/'` (以斜线开头和结尾)。
+If your site is deployed to a non-root URL, you will need to set the `base` option in `.vitepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'` (it should always start and end with a slash).
-所有静态资源路径都会自动处理以适配不同的 `base` 配置值。例如，在 markdown 中对 `public` 下的资源使用绝对路径引用：
+All your static asset paths are automatically processed to adjust for different `base` config values. For example, if you have an absolute reference to an asset under `public` in your markdown:
```md
-
+
```
-使用这种引用方式，当你更改 `base` 配置值时无需再做修改。
+You do **not** need to update it when you change the `base` config value in this case.
-但是，如果你正在创作一个动态链接到资源的主题组件，例如图片的 `src` 是基于主题设置的：
+However, if you are authoring a theme component that links to assets dynamically, e.g. an image whose `src` is based on a theme config value:
```vue
```
-在这种情况下，建议使用 VitePress 提供的 [`withBase` 辅助函数](/api/#withbase) 来引用静态资源：
+In this case it is recommended to wrap the path with the [`withBase` helper](/reference/runtime-api#withbase) provided by VitePress:
```vue
+
+
+
Custom Layout!
+
+
+ Custom 404 page!
+
+
+
+```
+
+The [`useData()`](/reference/runtime-api#usedata) helper provides us with all the runtime data we need to conditionally render different layouts. One of the other data we can access is the current page's frontmatter. We can leverage this to allow the end user to control the layout in each page. For example, the user can indicate the page should use a special home page layout with:
+
+```md
+---
+layout: home
+---
+```
+
+And we can adjust our theme to handle this:
+
+```vue{3,12-14}
+
+
+
+
Custom Layout!
+
+
+ Custom 404 page!
+
+
+ Custom home page!
+
+
+
+```
+
+You can, of course, split the layout into more components:
+
+```vue{3-5,12-15}
+
+
+
+
Custom Layout!
+
+
+
+
+
+```
+
+Consult the [Runtime API Reference](/reference/runtime-api) for everything available in theme components. In addition, you can leverage [Build-Time Data Loading](./data-loading) to generate data-driven layout - for example, a page that lists all blog posts in the current project.
+
+## Distributing a Custom Theme
+
+The easiest way to distribute a custom theme is by providing it as a [template repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).
+
+If you wish to distribute the theme as an npm package, follow these steps:
+
+1. Export the theme object as the default export in your package entry.
+
+2. If applicable, export your theme config type definition as `ThemeConfig`.
+
+3. If your theme requires adjusting the VitePress config, export that config under a package sub-path (e.g. `my-theme/config`) so the user can extend it.
+
+4. Document the theme config options (both via config file and frontmatter).
+
+5. Provide clear instructions on how to consume your theme (see below).
+
+## Consuming a Custom Theme
+
+To consume an external theme, import and re-export it from the custom theme entry:
+
+```js
+// .vitepress/theme/index.js
+import Theme from 'awesome-vitepress-theme'
+
+export default Theme
+```
+
+If the theme needs to be extended:
+
+```js
+// .vitepress/theme/index.js
+import Theme from 'awesome-vitepress-theme'
+
+export default {
+ extends: Theme,
+ enhanceApp(ctx) {
+ // ...
+ }
+}
+```
+
+If the theme requires special VitePress config, you will need to also extend it in your own config:
+
+```ts
+// .vitepress/theme/config.ts
+import baseConfig from 'awesome-vitepress-theme/config'
+
+export default {
+ // extend theme base config (if needed)
+ extends: baseConfig
+}
+```
+
+Finally, if the theme provides types for its theme config:
+
+```ts
+// .vitepress/theme/config.ts
+import baseConfig from 'awesome-vitepress-theme/config'
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'awesome-vitepress-theme'
+
+export default defineConfigWithTheme({
+ extends: baseConfig,
+ themeConfig: {
+ // Type is `ThemeConfig`
+ }
+})
+```
diff --git a/docs/zh/guide/customization-intro.md b/docs/zh/guide/customization-intro.md
deleted file mode 100644
index 2bd0f70d..00000000
--- a/docs/zh/guide/customization-intro.md
+++ /dev/null
@@ -1,220 +0,0 @@
-# 主题介绍 {#theme-introduction}
-
-VitePress 带有默认主题，并提供许多开箱即用的功能。通过下面列出的导航来了解有关每个功能的更多信息。
-
-- [导航](./theme-nav)
-- [侧边栏](./theme-sidebar)
-- [上一页/下一页链接](./theme-prev-next-link)
-- [编辑链接](./theme-edit-link)
-- [最后更新](./theme-last-updated)
-- [布局](./theme-layout)
-- [主页](./theme-home-page)
-- [团队页面](./theme-team-page)
-- [页脚](./theme-footer)
-- [搜索](./theme-search)
-- [Carbon Ads](./theme-carbon-ads)
-
-如果你没有找到所需的功能，或者你想创建自己的主题，你可以自定义 VitePress 以满足你的要求。在下面，我们将介绍自定义 VitePress 主题的方式。
-
-## 使用自定义主题 {#using-a-custom-theme}
-
-你可以通过添加 `.vitepress/theme/index.js` 或 `.vitepress/theme/index.ts` 文件 (“主题入口文件”) 来启用自定义主题。
-
-```
-.
-├─ docs
-│ ├─ .vitepress
-│ │ ├─ theme
-│ │ │ └─ index.js
-│ │ └─ config.js
-│ └─ index.md
-└─ package.json
-```
-
-VitePress 自定义主题是一个只包含四个属性的对象，定义如下：
-
-```ts
-interface Theme {
- Layout: Component // Vue 3 component
- NotFound?: Component
- enhanceApp?: (ctx: EnhanceAppContext) => void
- setup?: () => void
-}
-
-interface EnhanceAppContext {
- app: App // Vue 3 app instance
- router: Router // VitePress router instance
- siteData: Ref
-}
-```
-
-主题入口文件应将主题作为其默认导出：
-
-```js
-// .vitepress/theme/index.js
-import Layout from './Layout.vue'
-
-export default {
- // root component to wrap each page
- Layout,
-
- // this is a Vue 3 functional component
- NotFound: () => 'custom 404',
-
- enhanceApp({ app, router, siteData }) {
- // app is the Vue 3 app instance from `createApp()`.
- // router is VitePress' custom router. `siteData` is
- // a `ref` of current site-level metadata.
- }
-
- setup() {
- // this function will be executed inside VitePressApp's
- // setup hook. all composition APIs are available here.
- }
-}
-```
-
-... `Layout` 组件会如下所示：
-
-```vue
-
-
-
Custom Layout!
-
-
-
-
-```
-
-默认导出是自定义主题的唯一方式。 在自定义主题中，它就像普通的 Vite + Vue 3 应用程序一样工作。 注意，主题还需要[兼容 SSR](./using-vue#browser-api-access-restrictions)。
-
-要分发主题，只需在包入口里导出对象。要使用外部主题，请从自定义主题入口导入并重新导出：
-
-```js
-// .vitepress/theme/index.js
-import Theme from 'awesome-vitepress-theme'
-
-export default Theme
-```
-
-## 扩展默认主题 {#extending-the-default-theme}
-
-如果你想扩展和自定义默认主题，你可以从 `vitepress/theme` 导入它并在导出自定义主题中对其进行扩展。以下是一些常见自定义的示例：
-
-### 注册全局组件 {#registering-global-components}
-
-```js
-// .vitepress/theme/index.js
-import DefaultTheme from 'vitepress/theme'
-
-export default {
- ...DefaultTheme,
- enhanceApp({ app }) {
- // 注册一个全局组件
- app.component('MyGlobalComponent', /* ... */)
- }
-}
-```
-
-由于我们使用 Vite，你还可以利用 Vite 的[全局导入特性](https://vitejs.dev/guide/features.html#glob-import)自动注册组件目录。
-
-### 自定义 CSS {#customizing-css}
-
-默认主题 CSS 可通过覆盖根元素的 CSS 变量进行自定义：
-
-```js
-// .vitepress/theme/index.js
-import DefaultTheme from 'vitepress/theme'
-import './custom.css'
-
-export default DefaultTheme
-```
-
-```css
-/* .vitepress/theme/custom.css */
-:root {
- --vp-c-brand: #646cff;
- --vp-c-brand-light: #747bff;
-}
-```
-
-请参阅可以被覆盖的[默认的主题 CSS 变量](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css)。
-
-### Layout 组件插槽 {#layout-slots}
-
-默认主题 `` 组件有一些插槽，可用于在页面的某些位置注入内容。 这是一个将组件注入到之前的大纲中的示例：
-
-```js
-// .vitepress/theme/index.js
-import DefaultTheme from 'vitepress/theme'
-import MyLayout from './MyLayout.vue'
-
-export default {
- ...DefaultTheme,
- // override the Layout with a wrapper component that
- // injects the slots
- Layout: MyLayout
-}
-```
-
-```vue
-
-
-
-
-
-
- My custom sidebar top content
-
-
-
-```
-
-或者你也可以使用渲染函数。
-
-```js
-// .vitepress/theme/index.js
-import DefaultTheme from 'vitepress/theme'
-import MyComponent from './MyComponent.vue'
-
-export default {
- ...DefaultTheme,
- Layout() {
- return h(DefaultTheme.Layout, null, {
- 'aside-outline-before': () => h(MyComponent)
- })
- }
-}
-```
-
-默认主题布局中可用插槽的完整列表：
-
-- 当通过 frontmatter 开启 `layout: 'doc'` (default):
- - `doc-footer-before`
- - `doc-before`
- - `doc-after`
- - `aside-top`
- - `aside-bottom`
- - `aside-outline-before`
- - `aside-outline-after`
- - `aside-ads-before`
- - `aside-ads-after`
-- 当通过 frontmatter 开启 `layout: 'home'`:
- - `home-hero-before`
- - `home-hero-info`
- - `home-hero-after`
- - `home-features-before`
- - `home-features-after`
-- 一定有的:
- - `layout-top`
- - `layout-bottom`
- - `nav-bar-title-before`
- - `nav-bar-title-after`
- - `nav-bar-content-before`
- - `nav-bar-content-after`
- - `nav-screen-content-before`
- - `nav-screen-content-after`
diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md
index ee9c1c2b..0a6134e3 100644
--- a/docs/zh/guide/data-loading.md
+++ b/docs/zh/guide/data-loading.md
@@ -1,6 +1,15 @@
+# Build-Time Data Loading
+
+VitePress provides a feature called **data loaders** that allows you to load arbitrary data and import it from pages or components. The data loading is executed **only at build time**: the resulting data will be serialized as JSON in the final JavaScript bundle.
+
+Data loaders can be used to fetch remote data, or generate metadata based on local files. For example, you can use data loaders to parse all your local API pages and automatically generate an index of all API entries.
+
## Basic Usage
+A data loader file must end with either `.data.js` or `.data.ts`. The file should provide a default export of an object with the `load()` method:
+
```js
+// example.data.js
export default {
load() {
return {
@@ -10,30 +19,76 @@ export default {
}
```
+The loader module is evaluated only in Node.js, so you can import Node APIs and npm dependencies as needed.
+
+You can then import data from this file in `.md` pages and `.vue` components using the `data` named export:
+
+```html
+
+
+
+
+
+```
+
+
+
+
diff --git a/docs/zh/guide/vitepress-init.png b/docs/zh/guide/vitepress-init.png
new file mode 100644
index 00000000..d1805cf7
Binary files /dev/null and b/docs/zh/guide/vitepress-init.png differ
diff --git a/docs/zh/guide/what-is-vitepress.md b/docs/zh/guide/what-is-vitepress.md
index 8b63caf6..ec92b375 100644
--- a/docs/zh/guide/what-is-vitepress.md
+++ b/docs/zh/guide/what-is-vitepress.md
@@ -1,6 +1,26 @@
# What is VitePress?
-VitePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG). It is designed for building performant content-centric websites, such as this documentation you are reading right now. It also powers the documentation for [Vue.js](https://vuejs.org/), [Vite](https://vitejs.dev/), and many more. In a nutshell, VitePress takes your source content written in [Markdown](https://en.wikipedia.org/wiki/Markdown), applies a theme to it, and generates a directory of static HTML pages (and necessary asset files) that can be easily deployed anywhere.
+VitePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) designed for building fast, content-centric websites. In a nutshell, VitePress takes your source content written in [Markdown](https://en.wikipedia.org/wiki/Markdown), applies a theme to it, and generates static HTML pages that can be easily deployed anywhere.
+
+
+
+Just want to try it out? Skip to the [Quickstart](./getting-started).
+
+
+
+```
+
+## `useRoute`
+
+Returns the current route object with the following type:
+
+```ts
+interface Route {
+ path: string
+ data: PageData
+ component: Component | null
+}
+```
+
+## `useRouter`
+
+Returns the VitePress router instance so you can programmatically navigate to another page.
+
+```ts
+interface Router {
+ route: Route
+ go: (href?: string) => Promise
+}
+```
+
+## `withBase`
+
+- **Type**: `(path: string) => string`
+
+Appends the configured [`base`](/reference/site-config#base) to a given URL path. Also see [Base URL](/guide/asset-handling#base-url).
+
+## ``
+
+The `` component displays the rendered markdown contents. Useful [when creating your own theme](/guide/custom-theme).
+
+```vue
+
+
Custom Layout!
+
+
+```
+
+## ``
+
+The `` component renders its slot only at client side.
+
+Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser / DOM APIs in beforeMount or mounted hooks.
+
+If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them inside the `ClientOnly` component.
+
+```vue-html
+
+
+
+```
+
+## `$frontmatter`
+
+Directly access current page's [frontmatter](/guide/frontmatter) data in Vue expressions.
+
+```md
+---
+title: Hello
+---
+
+# {{ $frontmatter.title }}
+```
+
+## `$params`
+
+Directly access current page's [dynamic route params](/guide/routing#dynamic-routes) in Vue expressions.
+
+```md
+- package name: {{ $params.pkg }}
+- version: {{ $params.version }}
+```
diff --git a/docs/zh/reference/site-config.md b/docs/zh/reference/site-config.md
new file mode 100644
index 00000000..a784a945
--- /dev/null
+++ b/docs/zh/reference/site-config.md
@@ -0,0 +1,525 @@
+---
+outline: deep
+---
+
+# Site Config
+
+Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site.
+
+
+
+[[toc]]
+
+
+
+
+
+## Overview
+
+### Config Resolution
+
+The config file is always resolved from `/.vitepress/config.[ext]`, where `` is your VitePress [project root](/guide/routing#root-and-source-directory), and `[ext]` is one of the supported file extensions. TypeScript is supported out of the box. Supported extensions include `.js`, `.ts`, `.cjs`, `.mjs`, `.cts`, and `.mts`.
+
+It is recommended to use ES modules syntax in config files. The config file should default export an object:
+
+```ts
+export default {
+ // app level config options
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+ ...
+}
+```
+
+### Config Intellisense
+
+Using the `defineConfig` helper will provide TypeScript-powered intellisense for config options. Assuming your IDE supports it, this should work in both JavaScript and TypeScript.
+
+```js
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ // ...
+})
+```
+
+### Typed Theme Config
+
+By default, `defineConfig` helper expects the theme config type from default theme:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ // Type is `DefaultTheme.Config`
+ }
+})
+```
+
+If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument:
+
+```ts
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'your-theme'
+
+export default defineConfigWithTheme({
+ themeConfig: {
+ // Type is `ThemeConfig`
+ }
+})
+```
+
+## Site Metadata
+
+### title
+
+- Type: `string`
+- Default: `VitePress`
+- Can be overridden per page via [frontmatter](./frontmatter-config#title)
+
+Title for the site. When using the default theme, this will be displayed in the nav bar.
+
+It will also be used as the default suffix for all individual page titles, unless [`titleTemplate`](#titletemplate) is defined. An individual page's final title will be the text content of its first `
` header, combined with the global `title` as the suffix. For example with the following config and page content:
+
+```ts
+export default {
+ title: 'My Awesome Site'
+}
+```
+```md
+# Hello
+```
+
+The title of the page will be `Hello | My Awesome Site`.
+
+### titleTemplate
+
+- Type: `string | boolean`
+- Can be overridden per page via [frontmatter](./frontmatter-config#titletemplate)
+
+Allows customizing each page's title suffix or the entire title. For example:
+
+```ts
+export default {
+ title: 'My Awesome Site',
+ titleTemplate: 'Custom Suffix'
+}
+```
+```md
+# Hello
+```
+
+The title of the page will be `Hello | Custom Suffix`.
+
+To completely customize how the title should be rendered, you can use the `:title` symbol in `titleTemplate`:
+
+```ts
+export default {
+ titleTemplate: ':title - Custom Suffix'
+}
+```
+
+Here `:title` will be replaced with the text inferred from the page's first `
` header. The title of the previous example page will be `Hello - Custom Suffix`.
+
+The option can be set to `false` to disable title suffixes.
+
+### description
+
+- Type: `string`
+- Default: `A VitePress site`
+- Can be overridden per page via [frontmatter](./frontmatter-config#description)
+
+Description for the site. This will render as a `` tag in the page HTML.
+
+```ts
+export default {
+ description: 'A VitePress site'
+}
+```
+
+### head
+
+- Type: `HeadConfig[]`
+- Default: `[]`
+- Can be appended per page via [frontmatter](./frontmatter-config#head)
+
+Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags.
+
+```ts
+export default {
+ head: [
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
+ ]
+ // would render:
+ ]
+}
+```
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+### lang
+
+- Type: `string`
+- Default: `en-US`
+
+The lang attribute for the site. This will render as a `` tag in the page HTML.
+
+```ts
+export default {
+ lang: 'en-US'
+}
+```
+
+### base
+
+- Type: `string`
+- Default: `/`
+
+The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash.
+
+The base is automatically prepended to all the URLs that start with / in other options, so you only need to specify it once.
+
+```ts
+export default {
+ base: '/base/'
+}
+```
+
+## Routing
+
+### cleanUrls
+
+- Type: `boolean`
+- Default: `false`
+
+When set to `true`, VitePress will remove the trailing `.html` from URLs. Also see [Generating Clean URL](/guide/routing#generating-clean-url).
+
+::: warning Server Support Required
+Enabling this may require additional configuration on your hosting platform. For it to work, your server must be able to serve `/foo.html` when visiting `/foo` **without a redirect**.
+:::
+
+### rewrites
+
+- Type: `Record`
+
+Defines custom directory <-> URL mappings. See [Routing: Route Rewrites](/guide/routing#route-rewrites) for more details.
+
+```ts
+export default {
+ rewrites: {
+ 'source/:page': 'destination/:page'
+ }
+}
+```
+
+## Build
+
+### srcDir
+
+- Type: `string`
+- Default: `.`
+
+The directory where your markdown pages are stored, relative to project root. Also see [Root and Source Directory](/guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ srcDir: './src'
+}
+```
+
+### srcExclude
+
+- Type: `string`
+- Default: `undefined`
+
+A [glob pattern](https://github.com/mrmlnc/fast-glob#pattern-syntax) for matching markdown files that should be excluded as source content.
+
+```ts
+export default {
+ srcExclude: ['**/README.md', '**/TODO.md']
+}
+```
+
+### outDir
+
+- Type: `string`
+- Default: `./.vitepress/dist`
+
+The build output location for the site, relative to [project root](/guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ outDir: '../public'
+}
+```
+
+### cacheDir
+
+- Type: `string`
+- Default: `./.vitepress/cache`
+
+The directory for cache files, relative to [project root](/guide/routing#root-and-source-directory). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
+
+```ts
+export default {
+ cacheDir: './.vitepress/.vite'
+}
+```
+
+### ignoreDeadLinks
+
+- Type: `boolean | 'localhostLinks'`
+- Default: `false`
+
+When set to `true`, VitePress will not fail builds due to dead links. When set to `'localhostLinks'`, the build will fail on dead links, but won't check `localhost` links.
+
+```ts
+export default {
+ ignoreDeadLinks: true
+}
+```
+
+### mpa
+
+- Type: `boolean`
+- Default: `false`
+
+When set to `true`, the production app will be built in [MAP Mode](/guide/mpa-mode). MPA mode ships 0kb JavaScript by default, at the cost of disabling client-side navigation and requires explicit opt-in for interactivity.
+
+## Theming
+
+### appearance
+
+- Type: `boolean | 'dark'`
+- Default: `true`
+
+Whether to enable dark mode (by adding the `.dark` class to the `` element).
+
+- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme.
+- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it.
+- If the option is set to `false`, users will not be able to toggle the theme.
+
+This option injects an inline script that restores users settings from local storage using the `vitepress-theme-appearance` key. This ensures the `.dark` class is applied before the page is rendered to avoid flickering.
+
+### lastUpdated
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to get the last updated timestamp for each page using Git. The timestamp will be included in each page's page data, accessible via [`useData`](/reference/runtime-api#usedata).
+
+When using the default theme, enabling this option will display each page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option.
+
+## Customization
+
+### markdown
+
+- Type: `MarkdownOption`
+
+Configure Markdown parser options. VitePress uses [Markdown-it](https://github.com/markdown-it/markdown-it) as the parser, and [Shiki](https://shiki.matsu.io/) to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs.
+
+```js
+export default {
+ markdown: {
+ theme: 'material-theme-palenight',
+ lineNumbers: true
+ }
+}
+```
+
+Below are all the options that you can have in this object:
+
+```ts
+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
+
+- Type: `import('vite').UserConfig`
+
+Pass raw [Vite Config](https://vitejs.dev/config/) to internal Vite dev server / bundler.
+
+### vue
+
+- Type: `import('@vitejs/plugin-vue').Options`
+
+Pass raw [`@vitejs/plugin-vue` options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) to the internal plugin instance.
+
+## Build Hooks
+
+VitePress build hooks allow you to add new functionality and behaviors to your website:
+
+- Sitemap
+- Search Indexing
+- PWA
+- Teleports
+
+### buildEnd
+
+- Type: `(siteConfig: SiteConfig) => Awaitable`
+
+`buildEnd` is a build CLI hook, it will run after build (SSG) finish but before VitePress CLI process exits.
+
+```ts
+export default {
+ async buildEnd(siteConfig) {
+ // ...
+ }
+}
+```
+
+### postRender
+
+- Type: `(context: SSGContext) => Awaitable`
+
+`postRender` is a build hook, called when SSG rendering is done. It will allow you to handle the teleports content during SSG.
+
+```ts
+export default {
+ async postRender(context) {
+ // ...
+ }
+}
+```
+
+```ts
+interface SSGContext {
+ content: string
+ teleports?: Record
+ [key: string]: any
+}
+```
+
+### transformHead
+
+- Type: `(context: TransformContext) => Awaitable`
+
+`transformHead` is a build hook to transform the head before generating each page. It will allow you to add head entries that cannot be statically added to your VitePress config. You only need to return extra entries, they will be merged automatically with the existing ones.
+
+::: warning
+Don't mutate anything inside the `ctx`.
+:::
+
+```ts
+export default {
+ async transformHead(context) {
+ // ...
+ }
+}
+```
+
+```ts
+interface TransformContext {
+ siteConfig: SiteConfig
+ siteData: SiteData
+ pageData: PageData
+ title: string
+ description: string
+ head: HeadConfig[]
+ content: string
+}
+```
+
+### transformHtml
+
+- Type: `(code: string, id: string, ctx: TransformContext) => Awaitable`
+
+`transformHtml` is a build hook to transform the content of each page before saving to disk.
+
+::: warning
+Don't mutate anything inside the `ctx`. Also, modifying the html content may cause hydration problems in runtime.
+:::
+
+```ts
+export default {
+ async transformHtml(code, id, context) {
+ // ...
+ }
+}
+```
+
+### transformPageData
+
+- Type: `(pageData: PageData) => Awaitable | { [key: string]: any } | void>`
+
+`transformPageData` is a hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged into PageData.
+
+```ts
+export default {
+ async transformPageData(pageData) {
+ pageData.contributors = await getPageContributors(pageData.relativePath)
+ }
+
+ // or return data to be merged
+ async transformPageData(pageData) {
+ return {
+ contributors: await getPageContributors(pageData.relativePath)
+ }
+ }
+}
+```