- [VSCode](https://code.visualstudio.com/) is recommended, along with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar).
If using PNPM, you will notice a missing peer warning for `@docsearch/js`. This does not prevent VitePress from working. If you wish to suppress this warning, add the following to your `package.json`:
If you intend to perform customization that uses Vue components or APIs, you should also explicitly install `vue` as a peer dependency.
如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 `vue` 安装为 peer dependency。
:::
:::
## 文件结构 {#file-structure}
## 文件结构 {#file-structure}
If you are building a standalone VitePress site, you can scaffold the site in your current directory (`./`). However, if you are installing VitePress in an existing project alongside other source code, it is recommended to scaffold the site in a nested directory (e.g. `./docs`) so that it is separate from the rest of the project.
Assuming you chose to scaffold the VitePress project in `./docs`, the generated file structure should look like this:
假设你选择在 `./docs` 中搭建 VitePress 项目，生成的文件结构应该是这样的：
```
```
.
.
@ -89,15 +89,15 @@ Assuming you chose to scaffold the VitePress project in `./docs`, the generated
└─ package.json
└─ package.json
```
```
The `docs` directory is considered the **project root** of the VitePress site. The `.vitepress` directory is a reserved location for VitePress' config file, dev server cache, build output, and optional theme customization code.
By default, VitePress stores its dev server cache in `.vitepress/cache`, and the production build output in `.vitepress/dist`. If using Git, you should add them to your `.gitignore` file. These locations can also be [configured](../reference/site-config#outdir).
The config file (`.vitepress/config.js`) allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site:
You can also configure the behavior of the theme via the `themeConfig` option. Consult the [Config Reference](../reference/site-config) for full details on all config options.
Markdown files outside the `.vitepress` directory are considered **source files**.
`.vitepress` 目录之外的 Markdown 文件被视为**源文件**。
VitePress uses **file-based routing**: each `.md` file is compiled into a corresponding `.html` file with the same path. For example, `index.md` will be compiled into `index.html`, and can be visited at the root path `/` of the resulting VitePress site.
VitePress also provides the ability to generate clean URLs, rewrite paths, and dynamically generate pages. These will be covered in the [Routing Guide](./routing).
- To discover more about what you can do on the page, such as writing markdown content or using Vue Component, refer to the "Writing" section of the guide. A great place to start would be to learn about [Markdown Extensions](./markdown).
- To explore the features provided by the default documentation theme, check out the [Default Theme Config Reference](../reference/default-theme-config).
- If you want to further customize the appearance of your site, explore how to either [Extend the Default Theme](./extending-default-theme) or [Build a Custom Theme](./custom-theme).
VitePress comes with built in Markdown Extensions.
VitePress 带有内置的 Markdown 扩展。
## 标题锚点 {#header-anchors}
## 标题锚点 {#header-anchors}
Headers automatically get anchor links applied. Rendering of anchors can be configured using the `markdown.anchor` option.
标题会自动应用锚点。可以使用 `markdown.anchor` 选项配置锚点的渲染。
## 链接 {#links}
## 链接 {#links}
Both internal and external links gets special treatments.
内部和外部链接都会被特殊处理。
### 内部链接 {#internal-links}
### 内部链接 {#internal-links}
Internal links are converted to router link for SPA navigation. Also, every `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding URL `/`.
This is a special container that can be used to prevent style and router conflicts with VitePress. This is especially useful when you're documenting component libraries. You might also wanna check out [whyframe](https://whyframe.dev/docs/integrations/vitepress) for better isolation.
VitePress uses [Shiki](https://shiki.matsu.io/) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
Alternatively, it's possible to highlight directly in the line by using the `// [!code hl]` comment.
也可以使用 `// [!code hl]` 注释实现行高亮。
**Input**
**输入**
````
````
```js
```js
@ -367,7 +366,7 @@ export default {
```
```
````
````
**Output**
**输出**
```js
```js
export default {
export default {
@ -379,15 +378,15 @@ export default {
}
}
```
```
## Focus in Code Blocks {#focus-in-code-blocks}
## 代码块中聚焦 {#focus-in-code-blocks}
Adding the `// [!code focus]` comment on a line will focus it and blur the other parts of the code.
在某一行上添加 `// [!code focus]` 注释将聚焦它并模糊代码的其他部分。
Additionally, you can define a number of lines to focus using `// [!code focus:<lines>]`.
此外，可以使用 `// [!code focus:<lines>]` 定义要聚焦的行数。
**Input**
**输入**
Note that only one space is required after `!code`, here are two to prevent processing.
`!code` 后面只需要一个空格，为了展示原始的代码而不被实际渲染，这里有两个空格：
````
````
```js
```js
@ -401,7 +400,7 @@ export default {
```
```
````
````
**Output**
**输出**
```js
```js
export default {
export default {
@ -413,11 +412,11 @@ export default {
}
}
```
```
## Colored Diffs in Code Blocks {#colored-diffs-in-code-blocks}
## 代码块中的颜色差异 {#colored-diffs-in-code-blocks}
Adding the `// [!code --]` or `// [!code ++]` comments on a line will create a diff of that line, while keeping the colors of the codeblock.
Adding the `// [!code --]` or `// [!code ++]` comments on a line will create a diff of that line, while keeping the colors of the codeblock.
**Input**
**输入**
Note that only one space is required after `!code`, here are two to prevent processing.
Note that only one space is required after `!code`, here are two to prevent processing.
@ -434,7 +433,7 @@ export default {
```
```
````
````
**Output**
**输出**
```js
```js
export default {
export default {
@ -451,7 +450,7 @@ export default {
Adding the `// [!code warning]` or `// [!code error]` comments on a line will color it accordingly.
Adding the `// [!code warning]` or `// [!code error]` comments on a line will color it accordingly.
**Input**
**输入**
Note that only one space is required after `!code`, here are two to prevent processing.
Note that only one space is required after `!code`, here are two to prevent processing.
@ -468,7 +467,7 @@ export default {
```
```
````
````
**Output**
**输出**
```js
```js
export default {
export default {
@ -497,7 +496,7 @@ Please see [`markdown` options](../reference/site-config#markdown) for more deta
You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
**Input**
**输入**
````md
````md
```ts {1}
```ts {1}
@ -513,7 +512,7 @@ const line3 = 'This is line 3'
```
```
````
````
**Output**
**输出**
```ts {1}
```ts {1}
// line-numbers is disabled by default
// line-numbers is disabled by default
@ -541,7 +540,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
<<<@/filepath{highlightLines}
<<<@/filepath{highlightLines}
```
```
**Input**
**输入**
```md
```md
<<<@/snippets/snippet.js{2}
<<<@/snippets/snippet.js{2}
@ -551,7 +550,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
<<<@/snippets/snippet.js
<<<@/snippets/snippet.js
**Output**
**输出**
<<<@/snippets/snippet.js{2}
<<<@/snippets/snippet.js{2}
@ -561,7 +560,7 @@ The value of `@` corresponds to the source root. By default it's the VitePress p
You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath:
You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath:
**Input**
**输入**
```md
```md
<<<@/snippets/snippet-with-region.js#snippet{1}
<<<@/snippets/snippet-with-region.js#snippet{1}
@ -571,7 +570,7 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
<<<@/snippets/snippet-with-region.js
<<<@/snippets/snippet-with-region.js
**Output**
**输出**
<<<@/snippets/snippet-with-region.js#snippet{1}
<<<@/snippets/snippet-with-region.js#snippet{1}
@ -595,7 +594,7 @@ This is helpful if source language cannot be inferred from your file extension.
You can group multiple code blocks like this:
You can group multiple code blocks like this:
**Input**
**输入**
````md
````md
::: code-group
::: code-group
@ -624,7 +623,7 @@ export default config
:::
:::
````
````
**Output**
**输出**
::: code-group
::: code-group
@ -653,7 +652,7 @@ export default config
You can also [import snippets](#import-code-snippets) in code groups:
You can also [import snippets](#import-code-snippets) in code groups:
**Input**
**输入**
```md
```md
::: code-group
::: code-group
@ -669,7 +668,7 @@ You can also [import snippets](#import-code-snippets) in code groups:
:::
:::
```
```
**Output**
**输出**
::: code-group
::: code-group
@ -683,7 +682,7 @@ You can also [import snippets](#import-code-snippets) in code groups:
You can include a markdown file in another markdown file like this:
You can include a markdown file in another markdown file like this:
In VitePress, each Markdown file is compiled into HTML and then processed as a [Vue Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html). This means you can use any Vue features inside the Markdown, including dynamic templating, using Vue components, or arbitrary in-page Vue component logic by adding a `<script>` tag.
It's worth noting that VitePress leverages Vue's compiler to automatically detect and optimize the purely static parts of the Markdown content. Static contents are optimized into single placeholder nodes and eliminated from the page's JavaScript payload for initial visits. They are also skipped during client-side hydration. In short, you only pay for the dynamic parts on any given page.
Each Markdown file is first compiled into HTML and then passed on as a Vue component to the Vite process pipeline. This means you can use Vue-style interpolation in text:
每个 Markdown 文件首先被编译成 HTML，然后作为 Vue 组件传递给 Vite 流程管道。这意味着可以在文本中使用 Vue 的插值语法：
Root-level `<script>` and `<style>` tags in Markdown files work just like they do in Vue SFCs, including `<script setup>`, `<style module>`, etc. The main difference here is that there is no `<template>` tag: all other root-level content is Markdown. Also note that all tags should be placed **after** the frontmatter:
When used in Markdown, `<style scoped>` requires adding special attributes to every element on the current page, which will significantly bloat the page size. `<style module>` is preferred when locally-scoped styling is needed in a page.
You also have access to VitePress' runtime APIs such as the [`useData` helper](../reference/runtime-api#usedata), which provides access to current page's metadata:
You can import and use Vue components directly in Markdown files.
你可以直接在 Markdown 文件中导入和使用 Vue 组件。
### 在 Markdown 中导入组件 {#importing-in-markdown}
### 在 Markdown 中导入组件 {#importing-in-markdown}
If a component is only used by a few pages, it's recommended to explicitly import them where they are used. This allows them to be properly code-split and only loaded when the relevant pages are shown:
@ -122,45 +122,45 @@ This is a .md using a custom component
### 注册全局组件 {#registering-components-globally}
### 注册全局组件 {#registering-components-globally}
If a component is going to be used on most of the pages, they can be registered globally by customizing the Vue app instance. See relevant section in [Extending Default Theme](./extending-default-theme#registering-global-components) for an example.
Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise, it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
The HTML wrapped by `<code>` will be displayed as-is; only the HTML that is **not** wrapped will be parsed by Vue.
被 `<code>` 包裹的 HTML 将按原样显示，只有未包裹的 HTML 才会被 Vue 解析。
::: tip
::: tip
The output HTML is accomplished by [Markdown-it](https://github.com/Markdown-it/Markdown-it), while the parsed headers are handled by VitePress (and used for both the sidebar and document title).
输出 HTML 由 [Markdown-it](https://github.com/Markdown-it/Markdown-it) 完成，而解析的标题由 VitePress 处理 (并用于侧边栏和文档标题)。
:::
:::
## 转义 {#escaping}
## 转义 {#escaping}
You can escape Vue interpolations by wrapping them in a `<span>` or other elements with the `v-pre` directive:
This <spanv-pre>{{ will be displayed as-is }}</span>
This <spanv-pre>{{ will be displayed as-is }}</span>
```
```
**Output**
**输出**
<divclass="escape-demo">
<divclass="escape-demo">
<p>This <spanv-pre>{{ will be displayed as-is }}</span></p>
<p>This <spanv-pre>{{ will be displayed as-is }}</span></p>
</div>
</div>
Alternatively, you can wrap the entire paragraph in a `v-pre` custom container:
也可以将整个段落包装在 `v-pre` 自定义容器中：
```md
```md
::: v-pre
::: v-pre
@ -168,7 +168,7 @@ Alternatively, you can wrap the entire paragraph in a `v-pre` custom container:
:::
:::
```
```
**Output**
**输出**
<divclass="escape-demo">
<divclass="escape-demo">
@ -180,9 +180,9 @@ Alternatively, you can wrap the entire paragraph in a `v-pre` custom container:
## 代码块中不转义 {#unescape-in-code-blocks}
## 代码块中不转义 {#unescape-in-code-blocks}
By default, all fenced code blocks are automatically wrapped with `v-pre`, so no Vue syntax will be processd inside. To enable Vue-style interpolation inside fences, you can append the language with the `-vue` suffix, e.g. `js-vue`:
VitePress has [built-in support](https://vitejs.dev/guide/features.html#css-pre-processors) for CSS pre-processors: `.scss`, `.sass`, `.less`, `.styl` and `.stylus` files. There is no need to install Vite-specific plugins for them, but the corresponding pre-processor itself must be installed:
VitePress [内置支持](https://cn.vitejs.dev/guide/features.html#css-pre-processors) CSS 预处理器：`.scss`、`.sass`、.`less`、`.styl` 和 `.stylus` 文件。无需为它们安装 Vite 专用插件，但必须安装相应的预处理器：
```
```
# .scss and .sass {#.scss-and-.sass}
# .scss and .sass
npm install -D sass
npm install -D sass
# .less {#.less}
# .less
npm install -D less
npm install -D less
# .styl and .stylus {#.styl-and-.stylus}
# .styl and .stylus
npm install -D stylus
npm install -D stylus
```
```
Then you can use the following in Markdown and theme components:
然后你可以在 Markdown 和主题组件中使用以下内容：
```vue
```vue
<stylelang="sass">
<stylelang="sass">
@ -220,9 +220,9 @@ Then you can use the following in Markdown and theme components:
</style>
</style>
```
```
## 传递组件内容 {#using-teleports}
## 使用 teleport 传递组件内容 {#using-teleports}
Vitepress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in `<ClientOnly>` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](../reference/site-config#postrender).
Vitepress 目前只有使用 teleport 传送到 body 的 SSG 支持。对于其他地方，可以将它们包裹在内置的 `<ClientOnly>` 组件中，或者通过 [postRender 钩子](../reference/site-config#postrender)将 teleport 标签注入到最终页面 HTML 中的正确位置。
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.
VitePress 是一个[静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)，专为构建快速、以内容为中心的网站而设计。简而言之，VitePress 获取用 Markdown 编写的源内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。
Just want to try it out? Skip to the [Quickstart](./getting-started).
只是想尝试一下？跳到[快速开始](./getting-started)。
</div>
</div>
## 使用场景 {#use-cases}
## 使用场景 {#use-cases}
- **Documentation**
- **文档**
VitePress ships with a default theme designed for technical documentation, especially those that need to embed interactive demos. It powers this page you are reading right now, along with the documentation for [Vite](https://vitejs.dev/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Mermaid](https://mermaid.js.org/), [Wikimedia Codex](https://doc.wikimedia.org/codex/latest/), and many more.
VitePress supports [fully customized themes](./custom-theme), with the developer experience of a standard Vite + Vue application. Being built on Vite also means you can directly leverage Vite plugins from its rich ecosystem. In addition, VitePress provides flexible APIs to [load data](./data-loading) (local or remote) and [dynamically generate routes](./routing#dynamic-routes). You can use it to build almost anything as long as the data can be determined at build time.
VitePress 支持[完全的自定义主题](./custom-theme)，具有标准 Vite + Vue 应用程序的开发体验。基于 Vite 构建还意味着可以直接利用其丰富生态系统中的 Vite 插件。此外，VitePress 提供了灵活的 API 来[加载数据](./data-loading) (本地或远程)，也可以[动态生成路由](./routing#dynamic-routes)。只要可以在构建时确定数据，就可以使用它来构建几乎任何东西。
The official [Vue.js blog](https://blog.vuejs.org/) is a simple blog that generates its index page based on local content.
- **[Built-in Markdown Extensions:](./markdown)** Frontmatter, tables, syntax highlighting... you name it. Specifically, VitePress provides many advanced features for working with code blocks, making it ideal for highly technical documentation.
- **[Vue-Enhanced Markdown](./using-vue):** each Markdown page is also a Vue [Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html), thanks to Vue template's 100% syntax compatibility with HTML. You can embed interactivity in your static content using Vue templating features or imported Vue components.
Unlike many traditional SSGs, a website generated by VitePress is in fact a [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA).
The initial visit to any page will be served the static, pre-rendered HTML for blazing fast loading speed and optimal SEO. The page then loads a JavaScript bundle that turns the page into a Vue SPA ("hydration"). The hydration process is extremely fast: on [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), typical VitePress sites achieve near-perfect performance scores even on low-end mobile devices with a slow network.
More importantly, the SPA model leads to better user experience **after** the initial load. Subsequent navigation within the site will no longer cause a full page reload. Instead, the incoming page's content will be fetched and dynamically updated. VitePress also automatically pre-fetches page chunks for links that are within viewport. In most cases, post-load navigation will feel instant.
To be able to hydrate the dynamic Vue parts embedded inside static Markdown, each Markdown page is processed as a Vue component and compiled into JavaScript. This may sound inefficient, but the Vue compiler is smart enough to separate the static and dynamic parts, minimizing both the hydration cost and payload size. For the initial page load, the static parts are automatically eliminated from the JavaScript payload and skipped during hydration.
VitePress is the spiritual successor of VuePress. The original VuePress was based on Vue 2 and webpack. With Vue 3 and Vite under the hood, VitePress provides significantly better DX, better production performance, a more polished default theme, and a more flexible customization API.
The API difference between VitePress and VuePress mostly lies in theming and customization. If you are using VuePress 1 with the default theme, it should be relatively straightforward to migrate to VitePress.
VitePress 和 VuePress 之间的 API 区别主要在于主题和定制。如果您使用的是带有默认主题的 VuePress 1，迁移到 VitePress 应该相对简单。
There has also been effort invested into VuePress 2, which also supports Vue 3 and Vite with more compatibility with VuePress 1. However, maintaining two SSGs in parallel isn't sustainable, so the Vue team has decided to focus on VitePress as the main recommended SSG in the long run.
Xavi Lee
3 years ago