docs(zh): update `guide` translation

4 years ago · f95361ea10
parent 5385beac5d
commit f95361ea10
25 changed files with 2656 additions and 1 deletions
--- a/docs/zh/guide/api.md
+++ b/docs/zh/guide/api.md
@ -0,0 +1,93 @@
+# API 参考 {#api-reference}
+
+VitePress 提供了几个内置 API 来获取数据。VitePress 还提供了一些可以全局使用的内置组件。
+
+可以从 `vitepress` 全局引入辅助函数，通常用于自定义主题 Vue 组件。当然，它们也可以在 .md 页面中使用，因为 Markdown 文件会被编译成 Vue 单文件组件。
+
+以 `use*` 开头的方法表示它是一个 [Vue 3 组合式 API](https://cn.vuejs.org/guide/introduction.html#composition-api) 函数，只能在 `setup()` 内部使用或者使用 `<script setup>`。
+
+## `useData`
+
+返回页面的属性数据，返回的对象具有以下类型：
+
+```ts
+interface VitePressData {
+  site: Ref<SiteData>
+  page: Ref<PageData>
+  theme: Ref<any> // themeConfig from .vitepress/config.js
+  frontmatter: Ref<PageData['frontmatter']>
+  lang: Ref<string>
+  title: Ref<string>
+  description: Ref<string>
+  localePath: Ref<string>
+  isDark: Ref<boolean>
+}
+```
+
+**例子：**
+
+```vue
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme } = useData()
+</script>
+
+<template>
+  <h1>{{ theme.footer.copyright }}</h1>
+</template>
+```
+
+## `useRoute`
+
+返回具有以下类型的当前路由对象：
+
+```ts
+interface Route {
+  path: string
+  data: PageData
+  component: Component | null
+}
+```
+
+## `useRouter`
+
+返回 VitePress 路由实例，用来以编程方式导航到另一个页面。
+
+```ts
+interface Router {
+  route: Route
+  go: (href?: string) => Promise<void>
+}
+```
+
+## `withBase`
+
+- **Type**: `(path: string) => string`
+
+将配置的 [`base`](../config/app-configs#base) 添加到给定的 URL 路径。另请参阅 [Base URL](./asset-handling#base-url)。
+
+## `<Content />`
+
+`<Content />` 组件显示渲染的 markdown 内容。这在[创建你自己的主题时](./theme-introduction)很有用。
+
+```vue
+<template>
+  <h1>Custom Layout!</h1>
+  <Content />
+</template>
+```
+
+## `<ClientOnly />`
+
+`<ClientOnly />` 组件只在客户端渲染它的插槽。
+
+由于 VitePress 应用在生成静态文件之后会在 Node.js 中进行服务端渲染，因此任何 Vue 的使用都必须符合通用代码的要求。简而言之，确保只在 beforeMount 或 mounted 钩子中访问浏览器以及 DOM API。
+
+如果你正在使用不支持 SSR 的组件 (例如，包含自定义指令)，你可以将它们包装在 `ClientOnly` 组件中。
+
+```vue-html
+<ClientOnly>
+  <NonSSRFriendlyComponent />
+</ClientOnly>
+```
--- a/docs/zh/guide/asset-handling.md
+++ b/docs/zh/guide/asset-handling.md
@ -0,0 +1,55 @@
+# 资源处理 {#asset-handling}
+
+所有的 Markdown 文件都编译成 Vue 组件并由 [Vite](https://github.com/vitejs/vite) 处理。你可以**并且应该**使用相对路径引用资源：
+
+```md
+![一张图片](./image.png)
+```
+
+你可以在 markdown 文件、主题中的 `*.vue` 组件、styles 里和纯 `.css` 文件中通过使用绝对路径 (基于项目根目录) 或相对路径 (基于你的文件系统) 引用静态资源。相对路径的方式类似于使用 `vue-cli` 或 webpack 的 `file-loader` 时所习惯的写法。
+
+常规的图片、媒体和字体文件类型会被自动检测为静态资源。
+
+所有引用的资源，包括使用绝对路径的资源，都将被复制到 dist 文件夹中，并在生产打包后生成哈希文件名。但不会复制未引用的资源。与 `vue-cli` 一样，小于 4kb 的图片资源将编译成 base64 的内联样式。
+
+所有资源路径的引用，包括绝对路径，都应基于你的工作目录结构。
+
+## Public 文件 {#public-files}
+
+有时你可能需要提供一些 Markdown 或主题组件中未直接引用的静态资源 (例如，网站图标和 PWA 图标)。 项目根目录下的 `public` 目录 (如果你正在运行的是 `vitepress build docs`，则为 `docs` 文件夹) 将会保留，用以提供源代码中从未引用的静态资源 (例如 `robots.txt`) 和需要保留完全相同的文件名 (不生成哈希) 的资源。
+
+放在 `public` 中的资源将会直接复制到 dist 的根目录。
+
+注意，你应该使用从根目录开始以绝对路径引用放在 `public` 中的文件——例如，`public/icon.png` 在源代码中应始终引用为 `/icon.png`。
+
+## Base URL
+
+如果你的站点没有部署到根 URL，则需要在 `.vitepress/config.js` 中设置 `base` 选项。 例如，如果你要将站点部署到 `https://foo.github.io/bar/`，那么 `base` 应该设置为 `'/bar/'` (以斜线开头和结尾)。
+
+所有静态资源路径都会自动处理以适配不同的 `base` 配置值。例如，在 markdown 中对 `public` 下的资源使用绝对路径引用：
+
+```md
+![一张照片](/image-inside-public.png)
+```
+
+使用这种引用方式，当你更改 `base` 配置值时无需再做修改。
+
+但是，如果你正在创作一个动态链接到资源的主题组件，例如图片的 `src` 是基于主题设置的：
+
+```vue
+<img :src="theme.logoPath" />
+```
+
+在这种情况下，建议使用 VitePress 提供的 [`withBase` 辅助函数](./api#withbase) 来引用静态资源：
+
+```vue
+<script setup>
+import { withBase, useData } from 'vitepress'
+
+const { theme } = useData()
+</script>
+
+<template>
+  <img :src="withBase(theme.logoPath)" />
+</template>
+```
--- a/docs/zh/guide/configuration.md
+++ b/docs/zh/guide/configuration.md
@ -0,0 +1,27 @@
+# 配置 {#configuration}
+
+当没有任何配置的时候，页面将非常轻量，但用户也无法通过导航去访问网站。要自定义站点，首先在 docs 目录里创建一个 `.vitepress` 目录。 这是放置所有 VitePress 特定文件的地方。 这时候你的项目结构大概是这样的：
+
+```
+.
+├─ docs
+│  ├─ .vitepress
+│  │  └─ config.js
+│  └─ index.md
+└─ package.json
+```
+
+配置 VitePress 站点的基本文件是 `.vitepress/config.js`，它应该导出一个 JavaScript 对象：
+
+```js
+export default {
+  title: 'VitePress',
+  description: 'Just playing around.'
+}
+```
+
+在上面的示例中，该站点的使用 `VitePress` 作为标题，`Just play around.` 作为站点的描述。
+
+在[主题：介绍](./theme-introduction)里了解有关 VitePress 功能特性，以了解如何在此配置文件中配置特定功能。
+
+你还可以在[配置](../config/introduction)中找到所有配置项。
--- a/docs/zh/guide/deploying.md
+++ b/docs/zh/guide/deploying.md
@ -0,0 +1,203 @@
+# 部署 {#deploying}
+
+指南基于以下前置环境：
+
+- 文档放在项目的 `docs` 目录中。
+- 使用默认的构建输出位置 (`.vitepress/dist`)。
+- VitePress 作为本地依赖安装在项目中，并且在 `package.json` 中设置了以下脚本：
+
+  ```json
+  {
+    "scripts": {
+      "docs:build": "vitepress build docs",
+      "docs:serve": "vitepress serve docs"
+    }
+  }
+  ```
+
+::: tip 提示
+
+如果使用子目录(`https://example.com/subdir/`)作为部署站点，则必须在 `docs/.vitepress/config.js` 中将 `'/subdir/'` 设置为 [`base`](../config/app-configs#base) 的值。
+
+**示例：** 如果你使用 Github (或 GitLab) 页面并部署到 `user.github.io/repo/`，则将 `base` 设置为 `/repo/`。
+
+:::
+
+## 本地打包和测试 {#build-and-test-locally}
+
+- 运行此命令来打包文档：
+
+  ```sh
+  $ yarn docs:build
+  ```
+
+- 打包文档后，你可以通过运行命令在本地进行调试：
+
+  ```sh
+  $ yarn docs:serve
+  ```
+
+`serve` 命令将启动一个本地静态 Web 服务，该服务将在 `http://localhost:4173` 输出来自 `.vitepress/dist` 的文件。 这是检查生产版本在你的本地环境中是否正常的简易方法。
+
+- 可以通过传递 `--port` 作为参数来配置服务器运行的端口。
+
+  ```json
+  {
+    "scripts": {
+      "docs:serve": "vitepress serve docs --port 8080"
+    }
+  }
+  ```
+
+  现在 `docs:serve` 方法将在 `http://localhost:8080` 启动服务器。
+
+## 在 Netlify, Vercel, AWS Amplify, Cloudflare Pages 里部署 {#netlify-vercel-aws-amplify-cloudflare-pages-render}
+
+创建一个新项目并改成以下这些设置：
+
+- **Build Command:** `yarn docs:build`
+- **Output Directory:** `docs/.vitepress/dist`
+- **Node Version:** `14` (或者更高，默认值通常是 14 或 16，但在 Cloudflare Pages 上，默认值仍然是 12，所以你可能需要[修改](https://developers.cloudflare.com/pages/platform/build-configuration/))。
+
+::: warning 警告
+不要为 HTML 代码启用 _Auto Minify_ 之类的选项。 它将从输出中删除对 Vue 有意义的注释。如果它们被删除，可能会出现页面 hydration 不正确的问题。
+:::
+
+## GitHub Pages
+
+### 使用 GitHub Actions {#using-github-actions}
+
+1. 在你的主题配置文件 `docs/.vitepress/config.js` 中，将 `base` 属性设置为你的 GitHub 仓库的名称。 如果你打算将你的站点部署到`https://foo.github.io/bar/`，那么你应该将base设置为`'/bar/'`。 它应该始终以斜线开头和结尾。
+
+2. 在项目的 `.github/workflows` 目录中创建一个名为 `deploy.yml` 的文件，内容如下：
+
+   ```yaml
+   name: Deploy
+
+   on:
+     push:
+       branches:
+         - main
+
+   jobs:
+     deploy:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v3
+           with:
+             fetch-depth: 0
+         - uses: actions/setup-node@v3
+           with:
+             node-version: 16
+             cache: yarn
+         - run: yarn install --frozen-lockfile
+
+         - name: Build
+           run: yarn docs:build
+
+         - name: Deploy
+           uses: peaceiris/actions-gh-pages@v3
+           with:
+             github_token: ${{ secrets.GITHUB_TOKEN }}
+             publish_dir: docs/.vitepress/dist
+             # cname: example.com # if wanna deploy to custom domain
+   ```
+
+   ::: tip 提示
+   请替换对应的分支名称。例如，如果你要构建的分支是 `master`，则应将上述文件中的 `main` 替换为 `master`。
+   :::
+
+3. 现在提交你的代码并将其推送到 `main` 分支。
+
+4. 等待 action 完成。
+
+5. 在 git 仓库的 Setting 选项里，选择 `gh-pages` 分支作为 GitHub Pages 的来源。现在，你的文档将在每次推送时自动部署。
+
+## GitLab Pages
+
+### 使用 GitLab CI {#using-gitlab-ci}
+
+1. 将 `docs/.vitepress/config.js` 中的 `outDir` 设置为 `../public`。
+
+2. 在项目的根目录中创建一个名为 `.gitlab-ci.yml` 的文件，内容如下。每更改内容时，将会构建和部署你的站点：
+
+   ```yaml
+   image: node:16
+   pages:
+     cache:
+       paths:
+         - node_modules/
+     script:
+       - yarn install
+       - yarn docs:build
+     artifacts:
+       paths:
+         - public
+     only:
+       - main
+   ```
+
+## Azure Static Web Apps
+
+1. 参照[官方文档](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration)。
+
+2. 在配置文件中设置这些值(并删除不需要的值，例如 `api_location`)：
+
+   - **`app_location`**: `/`
+   - **`output_location`**: `docs/.vitepress/dist`
+   - **`app_build_command`**: `yarn docs:build`
+
+## Firebase
+
+1. 在项目根目录下创建 `firebase.json` 和 `.firebaserc`
+
+   `firebase.json`:
+
+   ```json
+   {
+     "hosting": {
+       "public": "docs/.vitepress/dist",
+       "ignore": []
+     }
+   }
+   ```
+
+   `.firebaserc`:
+
+   ```json
+   {
+     "projects": {
+       "default": "<YOUR_FIREBASE_ID>"
+     }
+   }
+   ```
+
+2. 执行 `yarn docs:build` 打包命令以后, 执行以下脚本进行部署:
+
+   ```sh
+   firebase deploy
+   ```
+
+## Surge
+
+1. 执行 `yarn docs:build` 打包命令以后，执行以下脚本进行部署:
+
+   ```sh
+   npx surge docs/.vitepress/dist
+   ```
+
+## Heroku
+
+1. 参照 [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) 的文档和指南。
+
+2. 在项目根目录下创建一个叫 `static.json` 的文件，内容如下:
+
+   ```json
+   {
+     "root": "docs/.vitepress/dist"
+   }
+   ```
+
+## Layer0
+
+参考[在 Layer0 里创建和部署 VitePress 应用](https://docs.layer0.co/guides/vitepress)。
--- a/docs/zh/guide/frontmatter.md
+++ b/docs/zh/guide/frontmatter.md
@ -0,0 +1,38 @@
+# Frontmatter
+
+任何包含 YAML frontmatter 的 Markdown 文件都将由 [gray-matter](https://github.com/jonschlinkert/gray-matter) 处理。 frontmatter 必须位于 Markdown 文件的顶部，并且必须采用在三点划线之间设置的有效 YAML 的形式。例如：
+
+```md
+---
+title: Docs with VitePress
+editLink: true
+---
+```
+
+在三点虚线之间，你可以设置[预定义变量](../config/frontmatter-configs)，甚至可以创建自己的自定义变量。 这些变量可以通过特殊的 <code>$frontmatter</code> 变量来使用。
+
+这是如何在 Markdown 文件中使用的例子：
+
+```md
+---
+title: Docs with VitePress
+editLink: true
+---
+
+# {{ $frontmatter.title }}
+
+Guide content
+```
+
+## Frontmatter 格式的其他写法 {#alternative-frontmatter-formats}
+
+VitePress 还支持 JSON frontmatter 语法，以花括号开头和结尾：
+
+```json
+---
+{
+  "title": "Blogging Like a Hacker",
+  "editLink": true
+}
+---
+```
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@ -0,0 +1,106 @@
+# 快速上手 {#getting-started}
+
+本节将帮助你从头开始构建一个基本的 VitePress 文档站点。如果你已经有一个现有项目并希望将文档保留在项目中，请从步骤2开始。
+
+你也可以在 [StackBlitz](https://vitepress.new/) 上在线尝试 VitePress，它直接在浏览器里运行基于 Vite 的站点。所以和你在本地构建的效果几乎是一样的，但是这种方式不需要在你的机器上安装任何东西。
+
+::: warning
+VitePress 目前处于 `alpha` 状态。它已经适合开箱即用地组织文档，但是具体配置以及和主题相关的 API 仍然可能在小的版本之间发生变化。
+:::
+
+## 步骤 1：创建一个项目 {#step-1-create-a-new-project}
+
+创建并进入新项目的目录。
+
+```sh
+$ mkdir vitepress-starter && cd vitepress-starter
+```
+
+用你喜欢的包管理工具初始化项目。
+
+```sh
+$ yarn init
+```
+
+## 步骤 2：安装 VitePress {#step-2-install-vitepress}
+
+添加 VitePress 和 Vue 作为项目的开发依赖项。
+
+```sh
+$ yarn add --dev vitepress vue
+```
+
+::: details 得到了 peer dependencies 警告？
+`@docsearch/js` 的 peer dependencies 存在某些问题。如果你看到某些命令由于它们而失败，你现在可以尝试以下解决方案：
+
+如果使用 pnpm，在 `package.json` 添加以下代码：
+
+```json
+"pnpm": {
+  "peerDependencyRules": {
+    "ignoreMissing": [
+      "@algolia/client-search"
+    ]
+  }
+}
+```
+
+:::
+
+创建你的第一篇文档。
+
+```sh
+$ mkdir docs && echo '# Hello VitePress' > docs/index.md
+```
+
+## 步骤 3：启动本地开发环境 {#step-3-boot-up-dev-environment}
+
+在 `package.json` 里添加一些脚本。
+
+```json
+{
+  ...
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:serve": "vitepress serve docs"
+  },
+  ...
+}
+```
+
+在本地启动文档服务。
+
+```sh
+$ yarn docs:dev
+```
+
+VitePress 将在 `http://localhost:5173` 启动一个支持热部署的本地开发服务环境。
+
+## 步骤 4：添加更多文档 {#step-4-add-more-pages}
+
+让我们再添加一个页面，创建一个名为 `getting-started.md` 的文件，与前面创建的 `index.md` 放在同一目录下。现在你的目录结构应该是这样的。
+
+```
+.
+├─ docs
+│  ├─ getting-started.md
+│  └─ index.md
+└─ package.json
+```
+
+接下来，访问 `http://localhost:5173/getting-started.html`，可以看到 `getting-started.md` 的内容。
+
+这就是 VitePress 的基本工作方式。目录结构与 URL 路径相对应。你可以添加文件，然后尝试访问它。
+
+## 下一步? {#what-s-next}
+
+到目前为止，你应该拥有一个基本但功能强大的 VitePress 文档站点。但现在用户还无法浏览该站点，因为它缺少菜单，类似于这个网站上的侧边栏。
+
+要启用这些导航，我们必须向站点添加一些配置。前往[配置指南](./configuration)了解如何配置 VitePress。
+
+如果你想了解更多关于可以在页面中执行的操作，例如编写 Markdown 或使用 Vue 组件，请查看文档的“编写”部分。[Markdown 指南](./markdown)将是一个很好的起点。
+
+如果你想了解如何自定义网站外观(主题)，并了解 VitePress 默认主题提供的功能，请访问[主题：简介](./theme-introduction)。
+
+当你的文档站点已经成形准备部署时，请务必阅读[部署指南](./deploying)。
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@ -0,0 +1,620 @@
+# Markdown 扩展 {#markdown-extensions}
+
+VitePress 带有内置的 Markdown 扩展。
+
+## 标题锚点 {#header-anchors}
+
+标题会自动获取锚点链接。可以通过 `markdown.anchor` 选项配置锚点的渲染。
+
+## 链接 {#links}
+
+内部链接和外部链接都会特殊处理。
+
+### 内部链接 {#internal-links}
+
+内部链接转换为 SPA 导航的路由链接。此外，每个子目录中包含的每个 `index.md` 都会自动转换为 `index.html`，并带有相应的URL `/`。
+
+举个例子，现在有以下目录结构：
+
+```
+.
+├─ index.md
+├─ foo
+│  ├─ index.md
+│  ├─ one.md
+│  └─ two.md
+└─ bar
+   ├─ index.md
+   ├─ three.md
+   └─ four.md
+```
+
+在 `foo/one.md` 中:
+
+```md
+[Home](/) <!-- 点击跳转到根目录的 index.md -->
+[foo](/foo/) <!-- 点击跳转到 foo 目录的 index.html -->
+[foo heading](./#heading) <!-- 锚点会定位到 foo 的 heading 标题处 -->
+[bar - three](../bar/three) <!-- 你可以不写后缀名 -->
+[bar - three](../bar/three.md) <!-- 也可以加 .md -->
+[bar - four](../bar/four.html) <!-- 或者加 .html -->
+```
+
+### 页面后缀 {#page-suffix}
+
+默认情况下，页面和内部链接会生成带有 `.html` 的后缀。
+
+### 外部链接 {#external-links}
+
+外部的链接会自动识别并生成 `target="_blank" rel="noreferrer"` 的链接，如下：
+
+- [vuejs.org](https://vuejs.org)
+- [VitePress github 地址](https://github.com/vuejs/vitepress)
+
+## Frontmatter
+
+[YAML frontmatter](https://jekyllrb.com/docs/front-matter/) 支持开箱即用：
+
+```yaml
+---
+title: Blogging Like a Hacker
+lang: en-US
+---
+```
+
+该数据可用于页面的其他部分，以及所有自定义和主题化组件中。
+
+了解更多，可以查看 [Frontmatter](./frontmatter)。
+
+## GitHub 风格的表格 {#github-style-tables}
+
+**输入**
+
+```
+| Tables        | Are           | Cool  |
+| ------------- |:-------------:| -----:|
+| col 3 is      | right-aligned | $1600 |
+| col 2 is      | centered      |   $12 |
+| zebra stripes | are neat      |    $1 |
+```
+
+**输出**
+
+| Tables        |      Are      |   Cool |
+| ------------- | :-----------: | -----: |
+| col 3 is      | right-aligned | \$1600 |
+| col 2 is      |   centered    |   \$12 |
+| zebra stripes |   are neat    |    \$1 |
+
+## Emoji :tada: {#emoji}
+
+**输入**
+
+```
+:tada: :100:
+```
+
+**输出**
+
+:tada: :100:
+
+可用的 emoji 可以通过[这里](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json)了解。
+
+## 表格内容 {#table-of-contents}
+
+**输入**
+
+```
+[[toc]]
+```
+
+**输出**
+
+[[toc]]
+
+可以使用 `markdown.toc` 选项配置 TOC 的渲染。
+
+## 自定义容器 {#custom-containers}
+
+自定义容器可以通过其类型、标题和内容来定义。
+
+### 默认标题 
+
+**输入**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**输出**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a dangerous warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+### 自定义标题 {#custom-title}
+
+你可以通过在容器的“类型”后面添加文本来设置自定义标题。
+
+**输入**
+
+````md
+::: danger STOP
+Danger zone, do not proceed
+:::
+
+::: details Click me to view the code
+```js
+console.log('Hello, VitePress!')
+```
+:::
+````
+
+**输出**
+
+::: danger STOP
+Danger zone, do not proceed
+:::
+
+::: details Click me to view the code
+```js
+console.log('Hello, VitePress!')
+```
+:::
+
+### `raw` {#raw}
+
+这是一个特殊的容器，可以用来防止样式和路由与 VitePress 冲突。当你记录组件库的文档时，这尤其有用。你可能还想查看一下 [whyframe](https://whyframe.dev/docs/integrations/vitepress)，以获得更好的隔离效果。
+
+**语法**
+
+```md
+::: raw
+Wraps in a <div class="vp-raw">
+:::
+```
+
+`vp-raw` 类也可以直接用于元素，样式隔离目前是可选择的。
+
+::: details 具体细节
+
+- Install required deps with your preferred package manager:
+
+  ```sh
+  $ yarn add -D postcss postcss-prefix-selector
+  ```
+
+- Create a file named `docs/.postcssrc.cjs` and add this to it:
+
+  ```js
+  module.exports = {
+    plugins: {
+      'postcss-prefix-selector': {
+        prefix: ':not(:where(.vp-raw *))',
+        includeFiles: [/vp-doc\.css/],
+        transform(prefix, _selector) {
+          const [selector, pseudo = ''] = _selector.split(/(:\S*)$/)
+          return selector + prefix + pseudo
+        }
+      }
+    }
+  }
+  ```
+
+:::
+
+## 在代码块中高亮语法 {#syntax-highlighting-in-code-blocks}
+
+VitePress 使用 [Shiki](https://shiki.matsu.io/) 的彩色文本来突出 Markdown 代码块中的语言语法。Shiki 支持多种编程语言，需要做的就是将有效的语言别名附加到代码块的开头反引号后：
+
+**输入**
+
+````
+```js
+export default {
+  name: 'MyComponent',
+  // ...
+}
+```
+````
+
+````
+```html
+<ul>
+  <li v-for="todo in todos" :key="todo.id">
+    {{ todo.text }}
+  </li>
+</ul>
+```
+````
+
+**输出**
+
+```js
+export default {
+  name: 'MyComponent'
+  // ...
+}
+```
+
+```html
+<ul>
+  <li v-for="todo in todos" :key="todo.id">
+    {{ todo.text }}
+  </li>
+</ul>
+```
+
+在 Shiki 的仓库里有对应支持的[语言列表](https://github.com/shikijs/shiki/blob/main/docs/languages.md)。
+
+你还可以在应用配置中自定义语法高亮主题。有关详细信息，请参阅 [`markdown` 选项](../config/app-configs#markdown)。
+
+## 代码块中定义行高亮 {#line-highlighting-in-code-blocks}
+
+**输入**
+
+````
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+除了单行之外，还可以指定多个单行、连续几行或者一起定义：
+
+- 连续几行: 例如 `{5-8}`、`{3-10}`、`{10-17}`
+- 多个单行: 例如 `{4,7,9}`
+- 连续几行和多个单行: 例如 `{4,7-13,16,23-27,40}`
+
+**输入**
+
+````
+```js{1,4,6-8}
+export default { // Highlighted
+  data () {
+    return {
+      msg: `Highlighted!
+      This line isn't highlighted,
+      but this and the next 2 are.`,
+      motd: 'VitePress is awesome',
+      lorem: 'ipsum'
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js{1,4,6-8}
+export default { // Highlighted
+  data () {
+    return {
+      msg: `Highlighted!
+      This line isn't highlighted,
+      but this and the next 2 are.`,
+      motd: 'VitePress is awesome',
+      lorem: 'ipsum',
+    }
+  }
+}
+```
+
+另外，也可以通过使用 `// [!code hl]` 注释直接实现行高亮。
+
+**输入**
+
+````
+```js
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!' // [!code  hl]
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!' // [!code hl]
+    }
+  }
+}
+```
+
+## 在代码块中聚焦 {#focus-in-code-blocks}
+
+在一行上添加 `// [!code focus]` 注释将聚焦这一行并模糊代码的其他部分。
+
+此外，可以使用 `// [!code focus:<lines>]` 定义聚焦的行数。
+
+**输入**
+
+````
+```js
+export default {
+  data () {
+    return {
+      msg: 'Focused!' // [!code  focus]
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+  data () {
+    return {
+      msg: 'Focused!' // [!code focus]
+    }
+  }
+}
+```
+
+## 代码块中的颜色差异 {#colored-diffs-in-code-blocks}
+
+在一行上添加 `// [!code --]` 或者 `// [!code ++]` 注释将实现该行差异的展示，同时保持代码块的颜色。
+
+**输入**
+
+````
+```js
+export default {
+  data () {
+    return {
+      msg: 'Removed' // [!code  --]
+      msg: 'Added' // [!code  ++]
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+  data () {
+    return {
+      msg: 'Removed' // [!code --]
+      msg: 'Added' // [!code ++]
+    }
+  }
+}
+```
+
+## 错误和警告
+
+在一行上添加 `// [!code warning]` 或者 `// [!code error]` 注释将使它变成相应的颜色。
+
+**输入**
+
+````
+```js
+export default {
+  data () {
+    return {
+      msg: 'Error', // [!code  error]
+      msg: 'Warning' // [!code  warning]
+    }
+  }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+  data () {
+    return {
+      msg: 'Error', // [!code error]
+      msg: 'Warning' // [!code warning]
+    }
+  }
+}
+```
+
+## 行号 {#line-numbers}
+
+可以通过配置为每个代码块启用行号：
+
+```js
+export default {
+  markdown: {
+    lineNumbers: true
+  }
+}
+```
+
+可以通过 [`markdown` 选项](../config/app-configs#markdown)了解更多。
+
+## 导入代码片段 {#import-code-snippets}
+
+你可以通过以下语法从现有文件中导入代码片段：
+
+```md
+<<< @/filepath
+```
+
+同时也支持[行高亮](#line-highlighting-in-code-blocks)：
+
+```md
+<<< @/filepath{highlightLines}
+```
+
+**输入**
+
+```md
+<<< @/snippets/snippet.js{2}
+```
+
+**代码文件**
+
+<<< @/snippets/snippet.js
+
+**输出**
+
+<<< @/snippets/snippet.js{2}
+
+::: tip
+`@` 相当于项目指定的源目录。默认情况下，它是 VitePress 项目根目录，当然也可以通过 `srcDir` 配置项配置。
+:::
+
+你也可以使用 [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) 来导入仅包含代码文件的部分。也可以在文件路径后的 `#` 后面提供自定义区域名称：
+
+**输入**
+
+```md
+<<< @/snippets/snippet-with-region.js#snippet{1}
+```
+
+**代码文件**
+
+<<< @/snippets/snippet-with-region.js
+
+**输出**
+
+<<< @/snippets/snippet-with-region.js#snippet{1}
+
+你还可以在大括号 (`{}`) 中指定语言：
+
+```md
+<<< @/snippets/snippet.cs{c#}
+
+<!-- 指定 行高亮: -->
+<<< @/snippets/snippet.cs{1,2,4-6 c#}
+```
+
+这在无法从文件扩展名中推断出源语言会很有用。
+
+## 包含其他 Markdown 文件 {#markdown-file-inclusion}
+
+你可以通过下面的写法在 markdown 文件中引入其他的markdown 文件：
+
+**输入**
+
+```md
+# Docs
+
+## Basics
+
+<!--@include: ./parts/basics.md-->
+```
+
+**Part 文件** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**等同于以下代码**
+
+```md
+# Docs
+
+## Basics
+
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+::: warning 警告
+注意，如果文件不存在，将不会抛出错误。因此，在使用此功能时，请确保按预期呈现内容。
+:::
+
+## 高级配置 {#advanced-configuration}
+
+VitePress使用 [markdown-it](https://github.com/markdown-it/markdown-it) 作为Markdown 渲染器。上面的许多扩展是通过自定义插件实现的。你可以使用`vitepress/config.js`中的 `Markdown` 选项进一步自定义 `Markdown-It` 实例：
+
+```js
+const anchor = require('markdown-it-anchor')
+
+module.exports = {
+  markdown: {
+    // options for markdown-it-anchor
+    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    anchor: {
+      permalink: anchor.permalink.headerLink()
+    },
+
+    // options for @mdit-vue/plugin-toc
+    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
+    toc: { level: [1, 2] },
+
+    config: (md) => {
+      // use more markdown-it plugins!
+      md.use(require('markdown-it-xxx'))
+    }
+  }
+}
+```
+
+通过[配置：应用配置](../config/app-configs#markdown)查看可配置属性的完整列表。
--- a/docs/zh/guide/migration-from-vitepress-0.md
+++ b/docs/zh/guide/migration-from-vitepress-0.md
@ -0,0 +1,23 @@
+# 从 VitePress 0.x 迁移 {#migration-from-vitepress-0-x}
+
+如果你来自 VitePress 0.x 版本，由于新功能和增强功能，会有一些重大更改。 请按照本指南了解如何将你的应用程序迁移到最新的 VitePress。
+
+## 应用配置 {#app-config}
+
+- 国际化功能尚未实现。
+
+## 主题配置 {#theme-config}
+
+- `sidebar` 选项改变了它的结构。
+   - `children` key现在命名为 `items`。
+   - 顶级项目目前可能不包含 `link`。我们打算把它转回来。
+- 删除了`repo`、`repoLabel`、`docsDir`、`docsBranch`、`editLinks`、`editLinkText`，以支持更灵活的 api。
+   - 要将带有图标的 GitHub 链接添加到导航，请使用[社交链接](./theme-nav#navigation-links)功能。
+   - 要添加“编辑此页面”功能，请使用[编辑链接](./theme-edit-link)功能。
+- `lastUpdated` 选项现在分为 `config.lastUpdated` 和 `themeConfig.lastUpdatedText`。
+- `carbonAds.carbon` 更改为 `carbonAds.code`。
+
+## Frontmatter 配置 {#frontmatter-config}
+
+- `home: true` 选项已更改为 `layout: home`。此外，还修改了许多与主页相关的设置以提供附加功能。详情请参阅[主页指南](./theme-home-page)。
+- `footer` 选项移至 [`themeConfig.footer`](../config/theme-configs#footer)。
--- a/docs/zh/guide/migration-from-vuepress.md
+++ b/docs/zh/guide/migration-from-vuepress.md
@ -0,0 +1,30 @@
+# 从 VuePress 迁移 {#migration-from-vuepress}
+
+## 配置 {#config}
+
+### 侧边栏 {#sidebar}
+
+侧边栏不再从 frontmatter 中自动获取。 你可以[自行阅读 frontmatter](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225) 来动态填充侧边栏。 [其他的工具方法](https://github.com/vuejs/vitepress/issues/96)将来可能会提供。
+
+## Markdown 
+
+### 图片 {#images}
+
+与 VuePress 不同，在使用静态图片时，VitePress 会根据你的配置自动处理这些 [`base`](./asset-handling#base-url)。
+
+因此，现在你可以在没有 `img` 标签的情况下渲染图像。
+
+```diff
+- <img :src="$withBase('/foo.png')" alt="foo">
+ ![foo](/foo.png)
+```
+
+::: warning 警告
+对于动态图像，你仍然需要 `withBase`，如[基本 URL 指南](./asset-handling#base-url)中所示。
+:::
+
+使用 `<img.*withBase\('(.*)'\).*alt="([^"]*)".*>` 正则表达式查找并替换为 `![$2]($1)` 用 `![](...)` 语法替换所有图像。
+
+---
+
+更多请继续关注...
--- a/docs/zh/guide/theme-badge.md
+++ b/docs/zh/guide/theme-badge.md
@ -0,0 +1,83 @@
+# 徽章 {#badge}
+
+徽章可以让你为你的标题添加状态。例如，指定该部分的类型或支持的版本可能是有用的。
+
+## 使用 {#usage}
+
+你可以使用全局生效的 `Badge` 组件：
+
+```html
+### Title <Badge type="info" text="default" />
+### Title <Badge type="tip" text="^1.9.0" />
+### Title <Badge type="warning" text="beta" />
+### Title <Badge type="danger" text="caution" />
+```
+
+代码将被渲染成下面这样：
+
+### Title <Badge type="info" text="default" />
+### Title <Badge type="tip" text="^1.9.0" />
+### Title <Badge type="warning" text="beta" />
+### Title <Badge type="danger" text="caution" />
+
+## 自定义 Children {#custom-children}
+
+`<Badge>` 接受 `children`，其将会显示在徽章上。
+
+```html
+### Title <Badge type="info">custom element</Badge>
+```
+
+### Title <Badge type="info">custom element</Badge> 
+
+## 自定义颜色 {#customize-type-color}
+
+你可以通过覆盖 css 变量来定制输入的 `<Badge />` 的背景颜色。以下是他的默认值。
+
+```css
+:root {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-text: var(--vp-c-text-2);
+  --vp-badge-info-bg: var(--vp-c-white-soft);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-1);
+  --vp-badge-tip-text: var(--vp-c-green-darker);
+  --vp-badge-tip-bg: var(--vp-c-green-dimm-3);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-1);
+  --vp-badge-warning-text: var(--vp-c-yellow-darker);
+  --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-1);
+  --vp-badge-danger-text: var(--vp-c-red-darker);
+  --vp-badge-danger-bg: var(--vp-c-red-dimm-3);
+}
+
+.dark {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-bg: var(--vp-c-black-mute);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-2);
+  --vp-badge-tip-text: var(--vp-c-green-light);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-2);
+  --vp-badge-warning-text: var(--vp-c-yellow-light);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-2);
+  --vp-badge-danger-text: var(--vp-c-red-light);
+}
+```
+
+## `<Badge>`
+
+`<Badge>` 组件接受下面的 props：
+
+```ts
+interface Props {
+  // When `<slot>` is passed, this value gets ignored.
+  text?: string
+
+  // Defaults to `tip`.
+  type?: 'info' | 'tip' | 'warning' | 'danger'
+}
+```
--- a/docs/zh/guide/theme-carbon-ads.md
+++ b/docs/zh/guide/theme-carbon-ads.md
@ -0,0 +1,22 @@
+# Carbon Ads
+
+VitePress 内置了对 [Carbon Ads](https://www.carbonads.net/) 的原生支持。通过在配置中定义Carbon Ads凭证，VitePress将在页面上显示广告。
+
+```js
+export default {
+  themeConfig: {
+    carbonAds: {
+      code: 'your-carbon-code',
+      placement: 'your-carbon-placement'
+    }
+  }
+}
+```
+
+这些值用于调用 carbon CDN 脚本，如下所示。
+
+```js
+`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
+```
+
+如需了解有关 Carbon Ads 配置的更多信息，请访问 [Carbon Ads 网站](https://www.carbonads.net/)。
--- a/docs/zh/guide/theme-edit-link.md
+++ b/docs/zh/guide/theme-edit-link.md
@ -0,0 +1,28 @@
+# 编辑链接 {#edit-link}
+
+编辑链接可以显示链接以编辑 Git 管理服务 (例如 GitHub 或 GitLab) 上的页面。 可以通过 `themeConfig.editLink` 选项配置来启用。
+
+```js
+export default {
+  themeConfig: {
+    editLink: {
+      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
+    }
+  }
+}
+```
+
+`pattern` 选项定义了链接的 URL 结构，`:path` 将被页面路径替换。
+
+默认情况下，这将在文档页面底部添加链接文本“编辑此页面”。你可以通过定义 `text` 选项来自定义此文本。
+
+```js
+export default {
+  themeConfig: {
+    editLink: {
+      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    }
+  }
+}
+```
--- a/docs/zh/guide/theme-footer.md
+++ b/docs/zh/guide/theme-footer.md
@ -0,0 +1,26 @@
+# 页脚 {#footer}
+
+配置 `themeConfig.footer` 可以使 VitePress 在页面底部展示全局的页脚。
+
+```ts
+export default {
+  themeConfig: {
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2019-present Evan You'
+    }
+  }
+}
+```
+
+```ts
+export interface Footer {
+  // The message shown rigth before copyright.
+  message?: string
+
+  // The actual copyright text.
+  copyright?: string
+}
+```
+
+注意，当[侧边栏](./theme-sidebar)可见时，不会显示页脚。
--- a/docs/zh/guide/theme-home-page.md
+++ b/docs/zh/guide/theme-home-page.md
@ -0,0 +1,116 @@
+# 主页
+
+VitePress 默认主题提供主页布局，你也可以在 [本站主页](../) 上看到使用的主页布局。 你可以通过在任何页面通过 [frontmatter](./frontmatter) 指定 `layout: home` 使用它。
+
+```yaml
+---
+layout: home
+---
+```
+
+但是，仅此选项不会有太大作用。 你可以通过设置额外的其他选项 (例如 `hero` 和 `features`) 将几个不同的预模板“部分”添加到主页。
+
+## Hero 部分
+
+Hero 部分位于主页的顶部。 以下是配置 Hero 部分的方法。
+
+```yaml
+---
+layout: home
+
+hero:
+  name: VitePress
+  text: Vite & Vue powered static site generator.
+  tagline: Lorem ipsum...
+  image:
+    src: /logo.png
+    alt: VitePress
+  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 {
+  // `text' 的字符串所示。带有品牌颜色，通常会很短，例如项目名称。
+  name?: string
+
+  // hero 部分的文本。这将被定义成`h1`标签
+  text: string
+
+  // Tagline 会展示在 `text` 下面。
+  tagline?: string
+
+  // action 按钮显示在 hero 区域。
+  actions?: HeroAction[]
+}
+
+interface HeroAction {
+  // 按钮的的主题颜色，默认为 `brand`。
+  theme?: 'brand' | 'alt'
+
+  // 按钮的内容。
+  text: string
+
+  // 按钮链接。
+  link: string
+}
+```
+
+### 自定义名字颜色 {#customizing-the-name-color}
+
+VitePress 使用品牌颜色 (`--vp-c-brand`) 作为 `name`。 但是，你可以通过覆盖 `--vp-home-hero-name-color` 变量来自定义此颜色。
+
+```css
+:root {
+  --vp-home-hero-name-color: blue;
+}
+```
+
+你也可以通过组合 `--vp-home-hero-name-background` 来进一步自定义它，以赋予 `name` 渐变颜色。
+
+```css
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
+}
+```
+
+## Features 部分 {#features-section}
+
+在 Features 部分，你可以在 hero 部分之后列出你想要显示的任意数量的功能。 要配置它，请在 `formatter` 中配置 `features`。
+
+```yaml
+---
+layout: home
+
+features:
+  - icon: ⚡️
+    title: Vite, The DX that can't be beat
+    details: Lorem ipsum...
+  - icon: 🖖
+    title: Power of Vue meets Markdown
+    details: Lorem ipsum...
+  - icon: 🛠️
+    title: Simple and minimal, always
+    details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+  // 在 feature 框里展示 icon，目前只支持 emoji
+  icon?: string
+
+  // feature 标题
+  title: string
+
+  // feature 详情
+  details: string
+}
+```
--- a/docs/zh/guide/theme-introduction.md
+++ b/docs/zh/guide/theme-introduction.md
@ -0,0 +1,219 @@
+# 主题介绍 {#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<SiteData>
+}
+```
+
+主题入口文件应将主题作为其默认导出：
+
+```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
+<!-- .vitepress/theme/Layout.vue -->
+<template>
+  <h1>Custom Layout!</h1>
+
+  <!-- this is where markdown content will be rendered -->
+  <Content />
+</template>
+```
+
+默认导出是自定义主题的唯一方式。 在自定义主题中，它就像普通的 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` 导入它并在导出自定义主题中对其进行扩展。以下是一些常见自定义的示例：
+
+### 注册全局组件 {#extending-the-default-theme}
+
+```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}
+
+默认主题 `<Layout/>` 组件有一些插槽，可用于在页面的某些位置注入内容。 这是一个将组件注入到之前的大纲中的示例：
+
+```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
+<!--.vitepress/theme/MyLayout.vue-->
+<script setup>
+import DefaultTheme from 'vitepress/theme'
+
+const { Layout } = DefaultTheme
+</script>
+
+<template>
+  <Layout>
+    <template #aside-outline-before>
+      My custom sidebar top content
+    </template>
+  </Layout>
+</template>
+```
+
+或者你也可以使用渲染函数。
+
+```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-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`
--- a/docs/zh/guide/theme-last-updated.md
+++ b/docs/zh/guide/theme-last-updated.md
@ -0,0 +1,20 @@
+# 最后更新 {#last-updated}
+
+最后内容的更新时间将显示在页面的右下角。要启用它，请在你的配置中添加 `lastUpdated` 选项。
+## 页面配置 {#page-configuration}
+
+添加 `lastUpdated` 选项到配置中去。
+```js
+export default {
+  lastUpdated: true
+}
+```
+
+## Frontmatter 配置 {#frontmatter-configuration}
+如果你想隐藏最后更新的文本，请对 `lastUpdated` 选项设置为 false。
+
+```yaml
+---
+lastUpdated: false
+---
+```
--- a/docs/zh/guide/theme-layout.md
+++ b/docs/zh/guide/theme-layout.md
@ -0,0 +1,37 @@
+# Layout
+
+你可以通过在页面 [frontmatter](./frontmatter) 中设置 `layout` 选项选择页面布局。有 3 个布局选项，`doc`、`page` 和 `home`。 如果未指定任何内容，则该页面被视为文档页面。
+
+```yaml
+---
+layout: doc
+---
+```
+
+## Doc 布局 {#doc-layout}
+
+`doc` 是默认布局，它将整个 Markdown 内容样式化为“文档”外观。它的工作原理是将整个内容包装在 `vp-doc` css 类中，并将样式应用于它下面的元素。
+
+几乎所有通用元素，例如 `p` 或 `h2` 都具有特殊样式。 因此，请记住，如果你在 Markdown 内容中添加任何自定义 HTML，这些元素也会受到这些样式的影响。
+
+同时还提供下面列出的文档特定功能。这些功能仅在此布局中生效。
+
+- 编辑链接
+- 上一页/下一页链接
+- 概述
+- [Carbon Ads](./theme-carbon-ads)
+
+## Page 布局 {#page-layout}
+
+选项 `page` 被视为“空白页”。 Markdown 仍然会被解析，并且所有 [Markdown 扩展](./markdown)与 `doc` 布局同样生效，但它不会有任何默认样式。
+
+page 布局可在 VitePress 主题不会影响标签的情况下让你自行设计所有内容。当你要创建自己的自定义页面时，这很有用。
+
+注意，即使在此布局中，如果页面具有匹配的侧边栏配置，侧边栏仍会显示。
+
+## Home 布局 {#home-layout}
+
+选项 `home` 将生成模板化的“主页”。 在此布局中，你可以设置额外的选项，例如 `hero` 和 `features`，以进一步自定义内容。请访问[主题：主页](./theme-home-page)了解更多详情。
+
+## No 布局 {#home-layout}
+如果你不想要任何布局，你可以通过在 frontmatter 中设置 `layout: false`。如果你想要一个完全可定制的登录页面 (默认情况下没有任何侧边栏、导航栏或页脚)，这个选项很有用。
--- a/docs/zh/guide/theme-nav.md
+++ b/docs/zh/guide/theme-nav.md
@ -0,0 +1,143 @@
+# 导航栏 {#nav}
+
+Nav 是显示在页面顶部的导航栏。 它包含站点标题、全局菜单链接等。
+
+## 网站的标题和 logo {#site-title-and-logo}
+
+默认情况下，导航的展示会引用 [`config.title`](../config/app-configs#title) 配置的站点标题。如果想更改导航上显示的内容，可以在 `themeConfig.siteTitle` 选项中定义自定义文本。
+
+```js
+export default {
+  themeConfig: {
+    siteTitle: 'My Custom Title'
+  }
+}
+```
+
+可以通过配置 `logo` 来展示网站的 logo，logo 应该直接放在 `public` 中，并定义为绝对路径。
+
+```js
+export default {
+  themeConfig: {
+    logo: '/my-logo.svg'
+  }
+}
+```
+
+添加 logo 后将会与网站标题一起显示。如果只想要展示 logo 而隐藏标题，请将 `siteTitle` 设置为 `false`。
+
+```js
+export default {
+  themeConfig: {
+    logo: '/my-logo.svg',
+    siteTitle: false
+  }
+}
+```
+
+如果你想添加 alt 属性或根据黑暗/光明模式定制它，你也可以传递一个对象作为 logo。详情请参见 [`themeConfig.logo`](../config/theme-configs#logo)。
+
+## 导航链接 {#navigation-links}
+
+你可以通过定义 `themeConfig.nav` 选项来添加链接到导航。
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      { text: 'Configs', link: '/configs' },
+      { text: 'Changelog', link: 'https://github.com/...' }
+    ]
+  }
+}
+```
+
+`text` 是 nav 中显示的实际文本，`link` 是单击文本时将导航到的链接。链接的路径设置为不带 `.md` 前缀的实际文件，并始终以 `/` 开头。
+
+导航链接也可以是下拉菜单。如果要定义为下拉菜单，请在链接选项上设置 `items`。
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          { text: 'Item A', link: '/item-1' },
+          { text: 'Item B', link: '/item-2' },
+          { text: 'Item C', link: '/item-3' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+注意，下拉菜单标题 (上例中的 `Dropdown Menu`) 不能配置 `link` 属性，因为它变成了打开下拉对话框的按钮。
+
+你还可以通过传入更多嵌套项来向下拉菜单项添加子项。
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide' },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          {
+            // Title for the section.
+            text: 'Section A Title',
+            items: [
+              { text: 'Section A Item A', link: '...' },
+              { text: 'Section B Item B', link: '...' }
+            ]
+          }
+        ]
+      },
+      {
+        text: 'Dropdown Menu',
+        items: [
+          {
+            // You may also omit the title.
+            items: [
+              { text: 'Section A Item A', link: '...' },
+              { text: 'Section B Item B', link: '...' }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 自定义链接的“active”状态 {#customize-link-s-active-state}
+
+当页面位于匹配路径下时，导航菜单项将高亮显示。可以通过定义 `activeMatch`，值为字符串类型的正则表达式。
+
+```js
+export default {
+  themeConfig: {
+    nav: [
+      // This link gets active state when the user is
+      // on `/config/` path.
+      {
+        text: 'Guide',
+        link: '/guide',
+        activeMatch: '/config/'
+      }
+    ]
+  }
+}
+```
+
+::: warning 警告
+`activeMatch` 应为正则表达式字符串，但你必须将其定义为字符串。我们不能在这里使用实际的 RegExp 对象，因为它在构建时不可序列化。
+:::
+
+## 社交链接 {#customize-link-s-active-state}
+
+点击这里查看支持的 [`socialLinks`](../config/theme-configs#sociallinks).
--- a/docs/zh/guide/theme-prev-next-link.md
+++ b/docs/zh/guide/theme-prev-next-link.md
@ -0,0 +1,29 @@
+# 上下页链接 {#prev-next-link}
+
+当你想定义上一个/下一个链接上显示与侧边栏不同的文本时，可以通过配置来自定义上下页链接。
+
+## 上页 {#prev}
+
+- 类型: `string`
+
+- 详情:
+
+  指定要在上一页的链接上显示的文本。
+
+  如果你没有在 frontmatter 中设置这个，文本将从侧边栏配置中推断出来。
+
+- 例子:
+
+```yaml
+---
+prev: 'Get Started | Markdown'
+---
+```
+
+## 下页 {#next}
+
+- 类型: `string`
+
+- 详情:
+
+  与 `prev` 同理
--- a/docs/zh/guide/theme-search.md
+++ b/docs/zh/guide/theme-search.md
@ -0,0 +1,3 @@
+# 搜索 {#search}
+
+文档即将更新...
--- a/docs/zh/guide/theme-sidebar.md
+++ b/docs/zh/guide/theme-sidebar.md
@ -0,0 +1,161 @@
+# 侧边栏 {#sidebar}
+
+侧边栏是文档的主要导航块。可以在 `themeConfig.sidebar` 中配置侧边栏菜单。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Introduction', link: '/introduction' },
+          { text: 'Getting Started', link: '/getting-started' },
+          ...
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 基本使用 {#the-basics}
+
+侧边栏菜单的最简单形式是传入一个链接数组。第一级项目定义了侧边栏部分。它应该包含 `text`，即该部分的标题，以及 `items`，即实际的导航链接。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Section Title A',
+        items: [
+          { text: 'Item A', link: '/item-a' },
+          { text: 'Item B', link: '/item-b' },
+          ...
+        ]
+      },
+      {
+        text: 'Section Title B',
+        items: [
+          { text: 'Item C', link: '/item-c' },
+          { text: 'Item D', link: '/item-d' },
+          ...
+        ]
+      }
+    ]
+  }
+}
+```
+
+每个 `link` 都应该指定以 `/` 开头的实际文件的路径。如果在链接末尾添加斜杠，它将显示相应目录的`index.md`。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          // This shows `/guide/index.md` page.
+          { text: 'Introduction', link: '/guide/' }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 多个侧边栏 {#multiple-sidebars}
+
+你可能会根据页面路径显示不同的侧边栏。例如，如本网站所示，你可能希望在文档中创建单独的内容部分，例如“指南”页面和“配置”页面。
+
+为此，首先将你的页面放到所在的目录中：
+
+```
+.
+├─ guide/
+│  ├─ index.md
+│  ├─ one.md
+│  └─ two.md
+└─ config/
+   ├─ index.md
+   ├─ three.md
+   └─ four.md
+```
+
+然后，更新配置以定义每个部分的侧边栏，不同的是，这次配置的是一个对象而不是数组。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: {
+      // 当用户在 `指南` 目录页面下将会展示这个侧边栏
+      '/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            // This shows `/guide/index.md` page.
+            { text: 'Index', link: '/guide/' }, // /guide/index.md
+            { text: 'One', link: '/guide/one' }, // /guide/one.md
+            { text: 'Two', link: '/guide/two' } // /guide/two.md
+          ]
+        }
+      ],
+
+      // 当用户在 `配置` 目录页面下将会展示这个侧边栏
+      '/config/': [
+        {
+          text: 'Config',
+          items: [
+            // This shows `/config/index.md` page.
+            { text: 'Index', link: '/config/' }, // /config/index.md
+            { text: 'Three', link: '/config/three' }, // /config/three.md
+            { text: 'Four', link: '/config/four' } // /config/four.md
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## 可折叠的侧边栏组 {#collapsible-sidebar-groups}
+
+通过向侧边栏组添加 `collapsible` 选项，它会显示一个切换按钮来隐藏或显示子菜单。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Section Title A',
+        collapsible: true,
+        items: [...]
+      },
+      {
+        text: 'Section Title B',
+        collapsible: true,
+        items: [...]
+      }
+    ]
+  }
+}
+```
+
+默认情况下，所有侧边栏都是展开的。如果你希望它们在初始页面加载时关闭，请将 `collapsed` 选项设置为 `true`。
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Section Title A',
+        collapsible: true,
+        collapsed: true,
+        items: [...]
+      }
+    ]
+  }
+}
+```
--- a/docs/zh/guide/theme-team-page.md
+++ b/docs/zh/guide/theme-team-page.md
@ -0,0 +1,255 @@
+<script setup>
+import { VPTeamMembers } from 'vitepress/theme'
+
+const members = [
+  {
+    avatar: 'https://github.com/yyx990803.png',
+    name: 'Evan You',
+    title: 'Creator',
+    links: [
+      { icon: 'github', link: 'https://github.com/yyx990803' },
+      { icon: 'twitter', link: 'https://twitter.com/youyuxi' }
+    ]
+  },
+  {
+    avatar: 'https://github.com/kiaking.png',
+    name: 'Kia King Ishii',
+    title: 'Developer',
+    links: [
+      { icon: 'github', link: 'https://github.com/kiaking' },
+      { icon: 'twitter', link: 'https://twitter.com/KiaKing85' }
+    ]
+  }
+]
+</script>
+
+# Team 页面 {#team-page}
+
+如果你想介绍你的团队，你可以使用团队组件来构建团队页面。有两种使用这些组件的方法。一种是将其嵌入到文档页面中，另一种是创建一个完整的团队页面。
+
+## 在页面中展示团队成员 {#show-team-members-in-a-page}
+
+你可以使用从 `vitepress/theme` 提供的 `<VPTeamMembers>` 组件在任何页面上显示团队成员列表。
+
+```html
+<script setup>
+import { VPTeamMembers } from 'vitepress/theme'
+
+const members = [
+  {
+    avatar: 'https://www.github.com/yyx990803.png',
+    name: 'Evan You',
+    title: 'Creator',
+    links: [
+      { icon: 'github', link: 'https://github.com/yyx990803' },
+      { icon: 'twitter', link: 'https://twitter.com/youyuxi' }
+    ]
+  },
+  ...
+]
+</script>
+
+# Our Team
+
+Say hello to our awesome team.
+
+<VPTeamMembers size="small" :members="members" />
+```
+
+以上将在卡片外观元素中显示团队成员。它应该显示成下面的内容。
+
+<VPTeamMembers size="small" :members="members" />
+
+`<VPTeamMembers>` 组件有 2 种不同的大小，`small` 和 `medium`。虽然归结为你的偏好，但通常“小”尺寸在文档页面中使用时应该更适合。此外，你可以为每个成员添加更多属性，例如添加“描述”或“赞助商”按钮。在 [`<VPTeamMembers>`](#vpteammembers) 中了解更多信息。
+
+在 doc 页面中的嵌入团队成员对小型团队非常有用，在这些团队中，拥有专用的完整团队页面可能太多，或者介绍部分成员作为文档上下文的参考也是有用的。
+
+如果你有大量成员，或者只是想有更多空间来展示团队成员，可以考虑[创建一个完整的团队页面](#create-a-full-team-page)。
+
+## 创建一个完整的团队页面 {#create-a-full-team-page}
+
+除了将团队成员添加到文档页面之外，你还可以创建一个完整的团队页面，类似于创建自定义[主页](./theme-home-page)的方式。
+
+要创建团队页面，首先，创建一个新的 md 文件。文件名不重要，不过这里我们命名为“team.md”。在这个文件中，设置 frontmatter 选项`layout: page`，然后你可以使用`TeamPage`组件来组成你的页面结构。
+
+```html
+---
+layout: page
+---
+<script setup>
+import {
+  VPTeamPage,
+  VPTeamPageTitle,
+  VPTeamMembers
+} from 'vitepress/theme'
+
+const members = [
+  {
+    avatar: 'https://www.github.com/yyx990803.png',
+    name: 'Evan You',
+    title: 'Creator',
+    links: [
+      { icon: 'github', link: 'https://github.com/yyx990803' },
+      { icon: 'twitter', link: 'https://twitter.com/youyuxi' }
+    ]
+  },
+  ...
+]
+</script>
+
+<VPTeamPage>
+  <VPTeamPageTitle>
+    <template #title>
+      Our Team
+    </template>
+    <template #lead>
+      The development of VitePress is guided by an international
+      team, some of whom have chosen to be featured below.
+    </template>
+  </VPTeamPageTitle>
+  <VPTeamMembers
+    :members="members"
+  />
+</VPTeamPage>
+```
+
+创建完整的团队页面时，请记住使用 `<VPTeamPage>` 组件包装所有组件。该组件将确保所有嵌套的团队相关组件都获得正确的布局结构，例如间距等。
+
+`<VPPageTitle>` 组件添加页面标题部分。标题是 `<h1>` 标题。 使用 `#title`和 `#lead` 插槽来记录你的团队。
+
+`<VPMembers>` 的工作方式与在文档页面中使用时相同。 它将显示成员列表。
+
+### 添加 “sections” 来区分不同的团队成员 {#add-sections-to-divide-team-members}
+
+你可以将 “sections” 添加到团队页面。例如，你可能有不同类型的团队成员，例如核心团队成员和社区合作伙伴。你可以将这些成员划分为多个部分，以更好地解释每个组的角色。
+
+为此，请将 `<VPTeamPageSection>` 组件添加到我们之前创建的 `team.md` 文件中。
+
+```html
+---
+layout: page
+---
+<script setup>
+import {
+  VPTeamPage,
+  VPTeamPageTitle,
+  VPTeamMembers,
+  VPTeamPageSection
+} from 'vitepress/theme'
+
+const coreMembers = [...]
+const partners = [...]
+</script>
+
+<VPTeamPage>
+  <VPTeamPageTitle>
+    <template #title>Our Team</template>
+    <template #lead>...</template>
+  </VPTeamPageTitle>
+  <VPTeamMembers size="medium" :members="coreMembers" />
+  <VPTeamPageSection>
+    <template #title>Partners</template>
+    <template #lead>...</template>
+    <template #members>
+      <VPTeamMembers size="small" :members="partners" />
+    </template>
+  </VPTeamPageSection>
+</VPTeamPage>
+```
+
+`<VPTeamPageSection>` 组件可以具有类似于 `VPTeamPageTitle` 组件的 `#title` 和 `#lead` 插槽，以及用于显示团队成员的 `#members` 插槽。
+
+请记住将 `<VPTeamMembers>` 组件放入 `#members` 插槽中。
+
+## `<VPTeamMembers>`
+
+`<VPTeamMembers>` 组件显示传入的成员列表。
+
+```html
+<VPTeamMembers
+  size="medium"
+  :members="[
+    { avatar: '...', name: '...' },
+    { avatar: '...', name: '...' },
+    ...
+  ]"
+/>
+```
+
+```ts
+interface Props {
+  // Size of each members. Defaults to `medium`.
+  size?: 'small' | 'medium'
+
+  // List of members to display.
+  members: TeamMember[]
+}
+
+interface TeamMember {
+  // Avatar image for the member.
+  avatar: string
+
+  // Name of the member.
+  name: string
+
+  // Title to be shown below member's name.
+  // e.g. Developer, Software Engineer, etc.
+  title?: string
+
+  // Organization that the member belongs.
+  org?: string
+
+  // URL for the organization.
+  orgLink?: string
+
+  // Description for the member.
+  desc?: string
+
+  // Social links. e.g. GitHub, Twitter, etc. You may pass in
+  // the Social Links object here.
+  // See: https://vitepress.vuejs.org/config/theme-configs.html#sociallinks
+  links?: SocialLink[]
+
+  // URL for the sponsor page for the member.
+  sponsor?: string
+}
+```
+
+## `<VPTeamPage>`
+
+创建完整团队页面时的根组件。 它只接受一个插槽。它将样式传入所有团队相关的组件。
+
+## `<VPTeamPageTitle>`
+
+添加页面的“标题”部分。 最好在 `<VPTeamPage>` 的开头使用。 它接受 `#title` 和 `#lead` 插槽。
+
+```html
+<VPTeamPage>
+  <VPTeamPageTitle>
+    <template #title>
+      Our Team
+    </template>
+    <template #lead>
+      The development of VitePress is guided by an international
+      team, some of whom have chosen to be featured below.
+    </template>
+  </VPTeamPageTitle>
+</VPTeamPage>
+```
+
+## `<VPTeamPageSection>`
+
+在团队页面中创建一个“部分”。它接受`#title`、`#lead` 和 `#members` 插槽。你可以在 `<VPTeamPage>` 中添加任意数量的“部分”。
+
+```html
+<VPTeamPage>
+  ...
+  <VPTeamPageSection>
+    <template #title>Partners</template>
+    <template #lead>Lorem ipsum...</template>
+    <template #members>
+      <VPTeamMembers :members="data" />
+    </template>
+  </VPTeamPageSection>
+</VPTeamPage>
+```
--- a/docs/zh/guide/using-vue.md
+++ b/docs/zh/guide/using-vue.md
@ -0,0 +1,261 @@
+# Markdown 中使用 Vue {#using-vue-in-markdown}
+
+在 VitePress 中，每个 markdown 文件都被编译成 HTML，然后其作为 Vue 单文件组件处理。这意味着你可以在 markdown 中使用所有的 Vue 功能，包括动态模板、Vue 组件或通过添加 `<script>` 标签使用 Vue 组件逻辑。
+
+同样重要的是要知道 VitePress 利用 Vue 3 的编译器来自动检测 markdown 中的纯静态的部分。静态内容被优化为独立的节点，从而减少页面的 JS 的开销。在客户端渲染数据期间，它们也会被跳过。简而言之，你需要额外处理的只有页面上的动态部分。
+
+## 模板语法 {#templating}
+
+### 插值 {#interpolation}
+
+每个 Markdown 文件首先编译成 HTML，然后作为 Vue 组件传递到 Vite 处理。这意味着你可以在文本中使用 Vue 风格的插值：
+
+**输入**
+
+```md
+{{ 1 + 1 }}
+```
+
+**输出**
+
+<div class="language-text"><pre><code>{{ 1 + 1 }}</code></pre></div>
+
+### 指令 {#directives}
+
+指令同样可用：
+
+**输入**
+
+```html
+<span v-for="i in 3">{{ i }}</span>
+```
+
+**输出**
+
+<div class="language-text"><pre><code><span v-for="i in 3">{{ i }} </span></code></pre></div>
+
+### 获取网站和页面数据 {#access-to-site-page-data}
+
+你可以在 `<script>` 里使用 [`useData` 辅助函数](./api#usedata) 并在页面里绑定数据。
+
+**输入**
+
+```html
+<script setup>
+import { useData } from 'vitepress'
+
+const { page } = useData()
+</script>
+
+<pre>{{ page }}</pre>
+```
+
+**输出**
+
+```json
+{
+  "path": "/using-vue.html",
+  "title": "Using Vue in Markdown",
+  "frontmatter": {}
+}
+```
+
+## 转义 {#escaping}
+
+默认情况下，栅栏式代码块会自动使用 `v-pre` 包装。要在内联代码片段或纯文本中展示 mustaches 或特定的 Vue 语法，你需要使用 `v-pre` 自定义容器包装一个段落：
+
+**输入**
+
+```md
+::: v-pre
+`{{ This will be displayed as-is }}`
+:::
+```
+
+**输出**
+
+::: v-pre
+`{{ This will be displayed as-is }}`
+:::
+
+## 使用组件 {#using-components}
+
+当你需要更大的灵活性时，VitePress 支持使用你自己的 Vue 组件扩展你的创作工具箱。
+
+### 在 markdown 中导入组件 {#importing-components-in-markdown}
+
+如果你的组件仅在少数地方使用，推荐的使用方法是在使用它的文件中导入组件。
+
+```md
+<script setup>
+import CustomComponent from '../components/CustomComponent.vue'
+</script>
+
+# Docs
+
+This is a .md using a custom component
+
+<CustomComponent />
+
+## More docs
+
+...
+```
+
+### 在主题中注册全局组件 {#registering-global-components-in-the-theme}
+
+如果要在文档中的多个页面中使用组件，则可以在主题中全局注册它们 (或作为默认 VitePress 主题扩展的一部分)。查看[主题指南](./theme-introduction)了解更多信息。
+
+在 `.vitepress/theme/index.js` 中，`enhanceApp` 函数接收 Vue `app` 实例，因此你可以在常规的 Vue 应用程序中 [注册组件](https://vuejs.org/guide/components/registration.html) 。
+
+```js
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('VueClickAwayExample', VueClickAwayExample)
+  }
+}
+```
+
+然后就可以在 markdown 文件里使用组件：
+
+```md
+# Vue Click Away
+
+<VueClickAwayExample />
+```
+
+::: warning 重要
+确保自定义组件的名称包含连字符或使用 PascalCase (大驼峰拼写)。否则，它将被视为内联元素并包裹在 `<p>` 标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定， `<p>` 标签中不允许放置任何块级元素。
+:::
+
+### 在标题中使用组件 <ComponentInHeader /> {#using-components-in-headers}
+
+你可以在标题中使用 Vue 组件，但请注意以下语法之间的区别：
+
+| Markdown                                                | Output HTML                               | Parsed Header |
+| ------------------------------------------------------- | ----------------------------------------- | ------------- |
+| <pre v-pre><code> # text &lt;Tag/&gt; </code></pre>     | `<h1>text <Tag/></h1>`                    | `text`        |
+| <pre v-pre><code> # text \`&lt;Tag/&gt;\` </code></pre> | `<h1>text <code>&lt;Tag/&gt;</code></h1>` | `text <Tag/>` |
+
+`<code>` 包裹的 HTML 将按原样显示；只有**未**包裹 `<code>` 的 HTML 才会被 Vue 解析。
+
+::: tip
+输出 HTML 由 [markdown-it](https://github.com/markdown-it/markdown-it) 完成，而解析的标题由 VitePress 处理(并用于侧边栏和文档标题)。
+:::
+
+## 使用 CSS 预处理器 {#using-css-pre-processors}
+
+VitePress 对 CSS 预处理器有[内置支持](https://vitejs.dev/guide/features.html#css-pre-processors)：`.scss`、`.sass`、`.less`， `.styl` 和 `.stylus` 文件。 不需要为它们安装 Vite 特定的插件，但必须安装相应的预处理器：
+
+```
+# .scss and .sass
+npm install -D sass
+
+# .less
+npm install -D less
+
+# .styl and .stylus
+npm install -D stylus
+```
+
+然后就可以在 Markdown 和主题组件中使用：
+
+```vue
+<style lang="sass">
+.title
+  font-size: 20px
+</style>
+```
+
+## 脚本和样式提升 {#script-style-hoisting}
+
+有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中使用原生的 `<script>` 或者 `<style>` 标签，它们将会从编译后的 HTML 文件中提取出来，并作为生成的 Vue 单文件组件的`<script>`和 `<style>` 标签:
+
+<p class="demo" :class="$style.example"></p>
+
+<style module>
+.example {
+  color: #41b883;
+}
+</style>
+
+<script>
+import ComponentInHeader from '../components/ComponentInHeader.vue'
+
+export default {
+  props: ['slot-key'],
+  components: { ComponentInHeader },
+  mounted () {
+    document.querySelector(`.${this.$style.example}`)
+      .textContent = 'This is rendered by inline script and styled by inline CSS'
+  }
+}
+</script>
+
+## 内置的组件 {#built-in-components}
+
+VitePress 提供了内置的 Vue 组件，例如 `ClientOnly` 和 `OutboundLink`，查看[全局组件指南](./api) 了解更多信息。
+
+**参见：**
+
+- [在标题中使用组件](#using-components-in-headers)
+
+## 浏览器 API 的访问限制 {#browser-api-access-restrictions}
+
+由于 VitePress 应用在生成静态构建时在 Node.js 中进行服务器渲染，因此任何 Vue 使用都必须符合[通用代码要求](https://vuejs.org/guide/scaling-up/ssr.html)。 简而言之，确保只在 `beforeMount` 或 `mounted` 钩子中访问浏览器以及 DOM API。
+
+如果你正在使用不支持 SSR 的组件 (例如，包含自定义指令)，你可以将它们包装在 `ClientOnly` 组件中。
+
+```md
+<ClientOnly>
+  <NonSSRFriendlyComponent />
+</ClientOnly>
+```
+
+注意，这不会修复**在导入时**访问浏览器 API 的组件或库。 要在导入时使用浏览器环境的代码，你需要在适当的生命周期挂钩中动态导入它们：
+
+```vue
+<script>
+export default {
+  mounted() {
+    import('./lib-that-access-window-on-import').then((module) => {
+      // use code
+    })
+  }
+}
+</script>
+```
+
+如果要使用 `export default` 导出的Vue 组件，你可以这样子动态注册：
+
+```vue
+<template>
+  <component
+    v-if="dynamicComponent"
+    :is="dynamicComponent">
+  </component>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dynamicComponent: null
+    }
+  },
+
+  mounted() {
+    import('./lib-that-access-window-on-import').then((module) => {
+      this.dynamicComponent = module.default
+    })
+  }
+}
+</script>
+```
+
+**参见：**
+
+- [Vue.js > 动态组件](https://cn.vuejs.org/guide/essentials/component-basics.html#dynamic-components)
--- a/docs/zh/guide/what-is-vitepress.md
+++ b/docs/zh/guide/what-is-vitepress.md
@ -0,0 +1,57 @@
+# VitePress 是什么? {#what-is-vitepress}
+
+VitePress 基于 [Vite](https://vitejs.dev/) 构建，是 [VuePress](https://vuepress.vuejs.org/) 的小兄弟。
+
+::: warning
+VitePress 目前处于 `alpha` 状态。它已经适合开箱即用地组织文档，但是具体配置以及和主题相关的 API 仍然可能在小的版本之间发生变化。
+:::
+
+## 动机 {#motivation}
+
+我们喜欢 VuePress v1，但是它是基于 Webpack 构建的，对于一个只有几个页面的简单文档站点来说，启动开发服务器所花费的时间让人难以忍受。即使是 HMR 更新也可能需要数秒才能在浏览器中反映出来。
+
+这是因为 VuePress v1 是一个基于 Webpack 的应用。即使只有两页，它也是一个完整的正在编译的 Webpack 项目 (包括所有主题源文件)。当项目有很多页面时，将会变得更慢——每个页面都必须先完全编译，然后才能显示内容！
+
+顺便说一句，Vite 很好地解决了这些问题：几乎即时启动的服务器，按需编译——只编译正在运行的页面以及闪电般的 HMR。另外，随着时间的推移，我在 VuePress v1 中注意到了一些额外的设计问题，但由于需要大量的重构，所以一直没有时间修复。
+
+现在，有了 Vite 和 Vue 3，是时候重新思考“基于 Vue 的静态站点生成器”到底能做什么了。
+
+## 相对与 VuePress v1 的改进 {#improvements-over-vuepress-v1}
+
+这是几点相对于 VuePress v1 的改进...
+
+### 使用 Vue 3 {#it-uses-vue-3}
+
+利用 Vue 3 改进的模板静态分析来尽可能地对静态内容进行字符串化。静态内容作为字符串文字而不是 JavaScript 渲染函数代码——因此 JS 解析成本要低得多，并且hydration (HTML 添加交互的过程) 也变得更快。
+
+> Hydration 一般指的是给服务器 返回的 HTML 添加交互的过程，它是在浏览器中执行的将静态 HTML 页面转为动态页面的技术
+
+注意，你依然可以在 Markdown 使用Vue 组件，VitePress 在应用优化的同时编译器会自动进行静态/动态分离，所以无需考虑这个问题。
+
+### 使用 Vite 作为引擎 {#it-uses-vite-under-the-hood}
+
+- 更快的本地服务启动
+- 更快的热更新
+- 更快的打包 (内部使用 Rollup)
+
+### 更小的页面体积 {#lighter-page-weight}
+
+Vue 3 的 tree-shaking + Rollup 代码拆分
+
+- 不在每个请求中为每个页面提供元数据。这使页面权重与总页数脱离。只有当前页面的元数据会被发送。客户端导航会同时获取新页面的组件和元数据。
+
+- 不使用 vue-router，因为 VitePress 的需求非常简单和具体 - 使用简单的自定义 router (200 行以下代码) 代替。
+
+### 其他不同 {#other-differences}
+
+VitePress 使用更少的配置：VitePress 旨在减少当前 VuePress 的复杂性，并从根本上使用极简主义风格重新开始。
+
+VitePress 只针对那些支持原生 ES 模块导入的浏览器。它鼓励使用原生的 JavaScript 而不进行转译，并使用 CSS 变量进行主题设计。
+
+## 这会成为未来的下一个 vuepress 吗？ {#will-this-become-the-next-vuepress-in-the-future}
+
+我们已经有了 [vuepress-next](https://github.com/vuepress/vuepress-next)，这将是 VuePress 的下一个主要版本。它还比 VuePress v1 做了很多改进，现在也支持 Vite。
+
+VitePress 与当前的 VuePress 生态系统 (主要是主题和插件) 不兼容。总体思路是，VitePress 将拥有一个更精简的主题 API (更偏向 JavaScript API 而不是文件布局约定)，并且可能没有插件 (可以在主题中完成所有定制)。
+
+关于这个话题有一个[正在进行的讨论](https://github.com/vuejs/vitepress/discussions/548)。有兴趣的话请留下你的想法！
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@ -22,7 +22,7 @@ features:
  - title: 简单易用是首要的设计理念
    details: 内容构建是以 Markdown 为中心的，它旨在帮助你专注于编写和以最少的配置进行部署。
  - title: 由 Vue 和 Markdown 驱动
-    details: 在 Markdown 中使用 Vue 的所有特性丰富内容，同时能够使用 Vue 自定义站点。
+    details: 在 Markdown 中使用 Vue 的所有特性的丰富内容，同时能够使用 Vue 自定义站点。
  - title: 是静态的，但也是动态的
    details: 真正的 SSG + SPA 构建。加载的是静态页面，但依然可以以 100% 的交互性吸引用户。
 ---