VitePress

简体中文

English

简体中文

English

Appearance

Embed AI chat in your VitePress using your own content. Open-source.Try now →

路由 ​

基于文件的路由 ​

VitePress 使用基于文件的路由，这意味着生成的 HTML 页面是从源 Markdown 文件的目录结构映射而来的。例如，给定以下目录结构：

.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md
.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

生成的 HTML 页面会是这样：

index.md                  -->  /index.html (可以通过 / 访问)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md  -->  /guide/getting-started.html
index.md                  -->  /index.html (可以通过 / 访问)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md  -->  /guide/getting-started.html

生成的 HTML 可以托管在任何可以提供静态文件的 Web 服务器上。

根目录和源目录 ​

VitePress 项目的文件结构中有两个重要的概念：项目根目录 (project root) 和源目录 (source directory)。

项目根目录 ​

项目根目录是 VitePress 将尝试寻找 .vitepress 特殊目录的地方。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的预留位置。

当你从命令行运行 vitepress dev 或 vitepress build 时，VitePress 将使用当前工作目录作为项目根目录。要将子目录指定为根目录，你需要将相对路径传递给命令。例如，如果你的 VitePress 项目位于 ./docs，你应该运行 vitepress dev docs：

.
├─ docs                    # project root
│  ├─ .vitepress           # config dir
│  ├─ getting-started.md
│  └─ index.md
└─ ...
.
├─ docs                    # project root
│  ├─ .vitepress           # config dir
│  ├─ getting-started.md
│  └─ index.md
└─ ...
sh
vitepress dev docs
vitepress dev docs

这将导致以下源代码到 HTML 的映射：

docs/index.md            -->  /index.html (可以通过 / 访问)
docs/getting-started.md  -->  /getting-started.html
docs/index.md            -->  /index.html (可以通过 / 访问)
docs/getting-started.md  -->  /getting-started.html

源目录 ​

源目录是你的 Markdown 源文件所在的位置。默认情况下，它与项目根目录相同。但是，你可以通过 srcDir 配置选项对其进行配置。

srcDir 选项是相对于项目根目录解析的。例如，对于 srcDir: 'src'，你的文件结构将如下所示：

.                                # project root
├─ .vitepress             # config dir
└─ src                      # source dir
   ├─ getting-started.md
   └─ index.md
.                                # project root
├─ .vitepress             # config dir
└─ src                      # source dir
   ├─ getting-started.md
   └─ index.md

生成的源代码到 HTML 的映射：

src/index.md            -->  /index.html (可以通过 / 访问)
src/getting-started.md  -->  /getting-started.html
src/index.md            -->  /index.html (可以通过 / 访问)
src/getting-started.md  -->  /getting-started.html

链接页面 ​

在页面之间链接时，你可以使用绝对路径和相对路径。请注意，虽然 .md 和 .html 扩展名都可以使用，但最佳做法是省略文件扩展名，以便 VitePress 可以根据你的配置生成最终 URL。

md
<!-- 正确做法 -->

[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)

<!-- 不正确做法 -->

[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)
<!-- 正确做法 -->

[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)

<!-- 不正确做法 -->

[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)

在资源处理中了解有关链接到资源（例如图像）的更多信息。

生成简洁的 URL ​

需要服务器支持

要使用 VitePress 提供简洁 URL，需要服务器端支持。

默认情况下，VitePress 将入站链接解析为以 .html 结尾的 URL。但是，一些用户可能更喜欢没有 .html 扩展名的“简洁 URL”——例如，example.com/path 而不是 example.com/path.html。

某些服务器或托管平台（例如 Netlify 或 Vercel）提供将 /foo 之类的 URL 映射到 /foo.html（如果存在）的功能，而无需重定向：

如果你可以使用此功能，你还可以启用 VitePress 自己的 cleanUrls 配置选项，以便：

  • 页面之间的入站链接是在没有 .html 扩展名的情况下生成的。
  • 如果当前路径以 .html 结尾，路由器将执行客户端重定向到无扩展路径。

但是，如果你无法为服务器配置此类支持（例如 GitHub 页面），则必须手动采用以下目录结构：

.
├─ getting-started
│  └─ index.md
├─ installation
│  └─ index.md
└─ index.md
.
├─ getting-started
│  └─ index.md
├─ installation
│  └─ index.md
└─ index.md

路由重写 ​

你可以自定义源目录结构和生成页面之间的映射。当你有一个复杂的项目结构时，它很有用。例如，假设你有一个包含多个包的 monorepo，并且希望将文档与源文件一起放置，如下所示：

.
├─ packages
│  ├─ pkg-a
│  │  └─ src
│  │      ├─ pkg-a-code.ts
│  │      └─ pkg-a-docs.md
│  └─ pkg-b
│     └─ src
│         ├─ pkg-b-code.ts
│         └─ pkg-b-docs.md
.
├─ packages
│  ├─ pkg-a
│  │  └─ src
│  │      ├─ pkg-a-code.ts
│  │      └─ pkg-a-docs.md
│  └─ pkg-b
│     └─ src
│         ├─ pkg-b-code.ts
│         └─ pkg-b-docs.md

你希望像这样生成 VitePress 页面：

packages/pkg-a/src/pkg-a-docs.md  -->  /pkg-a/index.html
packages/pkg-b/src/pkg-b-docs.md  -->  /pkg-b/index.html
packages/pkg-a/src/pkg-a-docs.md  -->  /pkg-a/index.html
packages/pkg-b/src/pkg-b-docs.md  -->  /pkg-b/index.html

你可以通过像这样配置 rewrites 选项来实现此目的：

ts
// .vitepress/config.js
export default {
	rewrites: {
		'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
		'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md',
	},
}
// .vitepress/config.js
export default {
	rewrites: {
		'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
		'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md',
	},
}

rewrites 选项还支持动态路由参数。在上面的示例中，如果你有很多包，则列出所有路径会很冗长。鉴于它们都具有相同的文件结构，你可以像这样简化配置：

ts
export default {
	rewrites: {
		'packages/:pkg/src/(.*)': ':pkg/index.md',
	},
}
export default {
	rewrites: {
		'packages/:pkg/src/(.*)': ':pkg/index.md',
	},
}

重写路径是使用 path-to-regexp 包编译的 - 请参阅其文档以获取更高级的语法。

开启重写功能时使用相对链接

启用重写后，相对链接应基于重写的路径。例如，为了创建从 packages/pkg-a/src/pkg-a-code.md 到 packages/pkg-b/src/pkg-b-code.md 的相对链接，你应该使用：

md
[Link to PKG B](../pkg-b/pkg-b-code)
[Link to PKG B](../pkg-b/pkg-b-code)

动态路由 ​

你可以使用单个 Markdown 文件和动态数据生成许多页面。例如，你可以创建一个 packages/[pkg].md 文件，为项目中的每个包生成相应的页面。这里，[pkg] 段是一个路由参数，用于区分每个页面。

路径加载文件 ​

由于 VitePress 是静态站点生成器，因此必须在构建时确定可能的页面路径。因此，动态路由页面必须伴随路径加载文件。对于 packages/[pkg].md，我们需要 packages/[pkg].paths.js（也支持 .ts）：

.
└─ packages
   ├─ [pkg].md         # route template
   └─ [pkg].paths.js   # route paths loader
.
└─ packages
   ├─ [pkg].md         # route template
   └─ [pkg].paths.js   # route paths loader

路径加载器应该提供一个带有 paths 方法的对象作为其默认导出。paths 方法应返回具有 params 属性的对象数组。这些对象中的每一个都将生成一个相应的页面。

给定以下 paths 数组：

js
// packages/[pkg].paths.js
export default {
	paths() {
		return [{ params: { pkg: 'foo' } }, { params: { pkg: 'bar' } }]
	},
}
// packages/[pkg].paths.js
export default {
	paths() {
		return [{ params: { pkg: 'foo' } }, { params: { pkg: 'bar' } }]
	},
}

生成的 HTML 页面将会是：

.
└─ packages
   ├─ foo.html
   └─ bar.html
.
└─ packages
   ├─ foo.html
   └─ bar.html

多参数 ​

动态路由可以包含多个参数：

File Structure

.
└─ packages
   ├─ [pkg]-[version].md
   └─ [pkg]-[version].paths.js
.
└─ packages
   ├─ [pkg]-[version].md
   └─ [pkg]-[version].paths.js

路径加载器

js
export default {
	paths: () => [
		{ params: { pkg: 'foo', version: '1.0.0' } },
		{ params: { pkg: 'foo', version: '2.0.0' } },
		{ params: { pkg: 'bar', version: '1.0.0' } },
		{ params: { pkg: 'bar', version: '2.0.0' } },
	],
}
export default {
	paths: () => [
		{ params: { pkg: 'foo', version: '1.0.0' } },
		{ params: { pkg: 'foo', version: '2.0.0' } },
		{ params: { pkg: 'bar', version: '1.0.0' } },
		{ params: { pkg: 'bar', version: '2.0.0' } },
	],
}

输出

.
└─ packages
   ├─ foo-1.0.0.html
   ├─ foo-2.0.0.html
   ├─ bar-1.0.0.html
   └─ bar-2.0.0.html
.
└─ packages
   ├─ foo-1.0.0.html
   ├─ foo-2.0.0.html
   ├─ bar-1.0.0.html
   └─ bar-2.0.0.html

动态生成路径 ​

路径加载器模块在 Node.js 中运行，并且仅在构建期间执行。你可以使用本地或远程的任何数据动态生成路径数组。

从本地文件生成路径：

js
import fs from 'fs'
export default {
	paths() {
		return fs.readdirSync('packages').map((pkg) => {
			return { params: { pkg } }
		})
	},
}
import fs from 'fs'
export default {
	paths() {
		return fs.readdirSync('packages').map((pkg) => {
			return { params: { pkg } }
		})
	},
}

从远程数据生成路径：

js
export default {
	async paths() {
		const pkgs = await (await fetch('https://my-api.com/packages')).json()
		return pkgs.map((pkg) => {
			return {
				params: {
					pkg: pkg.name,
					version: pkg.version,
				},
			}
		})
	},
}
export default {
	async paths() {
		const pkgs = await (await fetch('https://my-api.com/packages')).json()
		return pkgs.map((pkg) => {
			return {
				params: {
					pkg: pkg.name,
					version: pkg.version,
				},
			}
		})
	},
}

访问页面中的参数 ​

你可以使用参数将附加数据传递到每个页面。Markdown 路由文件可以通过 $params 全局属性访问 Vue 表达式中的当前页面参数：

md
- package name: {{ $params.pkg }}
- version: {{ $params.version }}
- package name: {{ $params.pkg }}
- version: {{ $params.version }}

你还可以通过 useData runtime API 访问当前页面的参数。这在 Markdown 文件和 Vue 组件中都可用：

vue
<script setup>
import { useData } from 'vitepress'
// params is a Vue ref
const { params } = useData()
console.log(params.value)
</script>
<script setup>
import { useData } from 'vitepress'
// params is a Vue ref
const { params } = useData()
console.log(params.value)
</script>

渲染原始内容 ​

传递给页面的参数将在客户端 JavaScript payload 中序列化，因此你应该避免在参数中传递大量数据，例如从远程 CMS 获取的原始 Markdown 或 HTML 内容。

相反，你可以使用每个路径对象上的 content 属性将此类内容传递到每个页面：

js
export default {
  paths() {
    async paths() {
      const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
      return posts.map((post) => {
        return {
          params: { id: post.id },
          content: post.content // raw Markdown or HTML
        }
      })
    }
  }
}
export default {
  paths() {
    async paths() {
      const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
      return posts.map((post) => {
        return {
          params: { id: post.id },
          content: post.content // raw Markdown or HTML
        }
      })
    }
  }
}

然后，使用以下特殊语法将内容呈现为 Markdown 文件本身的一部分：

md
<!-- @content -->
<!-- @content -->

Released under the MIT License.

Copyright © 2019-present Evan You