VitePress 路由重写：自定义目录结构与页面生成

在使用VitePress构建文档网站时，你可能会遇到项目结构复杂的情况，特别是当你的项目是一个包含多个包的monorepo时。为了更好地组织和管理文档，你可能希望将文档文件放置在源代码旁边。然而，VitePress默认会按照特定的目录结构生成页面。为了解决这个问题，VitePress提供了路由重写功能，允许你自定义源目录结构与生成页面之间的映射。

一、路由重写的基本概念

路由重写是VitePress中的一个强大功能，它允许你定义源文件与目标生成页面之间的自定义映射关系。通过配置rewrites选项，你可以指定源文件路径和对应的生成路径，从而实现灵活的页面生成策略。

二、配置路由重写

要在VitePress中配置路由重写，你需要在.vitepress/config.js文件中添加rewrites选项。以下是一个基本的配置示例：

// .vitepress/config.js
export default {
  rewrites: {
    // 将packages/pkg-a/src/pkg-a-docs.md映射到/pkg-a/index.html
    'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
    // 将packages/pkg-b/src/pkg-b-docs.md映射到/pkg-b/index.html
    'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md'
  }
}

在上述配置中，我们指定了两个具体的重写规则。当VitePress处理文档时，它会根据这些规则将指定的源文件映射到对应的生成路径。

三、动态路由参数

如果你的项目包含许多包，并且每个包都有相同的文件结构，那么逐一列出所有路径可能会非常繁琐。为了简化配置，你可以使用动态路由参数。以下是一个使用动态路由参数的配置示例：

// .vitepress/config.js
export default {
  rewrites: {
    // 使用动态参数:pkg来匹配任意包名，并将src下的任意文件映射到包名下的index.md
    'packages/:pkg/src/(.*)': ':pkg/index.md'
  }
}

在这个配置中，:pkg是一个动态参数，它可以匹配任意包名。(.*)是一个通配符，用于匹配src目录下的任意文件。这样，无论你有多少个包，只要它们遵循相同的文件结构，这个配置都可以工作。

四、相对链接与重写

当启用路由重写时，你需要注意相对链接的处理。相对链接应该基于重写后的路径来构建。例如，如果你想在packages/pkg-a/src/pkg-a-code.md中创建一个指向packages/pkg-b/src/pkg-b-code.md的相对链接，你应该这样写：

// 在packages/pkg-a/src/pkg-a-code.md中
[Link to PKG B](../pkg-b/pkg-b-code)

在这个例子中，../pkg-b/pkg-b-code是基于重写后的路径构建的相对链接。它会正确地指向pkg-b包中的pkg-b-code文件。

五、总结

VitePress的路由重写功能为复杂项目结构提供了灵活的页面生成策略。通过配置rewrites选项，你可以轻松地自定义源文件与生成页面之间的映射关系。无论是对于monorepo项目还是其他复杂结构，路由重写都能帮助你更好地组织和管理文档。同时，注意在处理相对链接时要基于重写后的路径来构建，以确保链接的正确性。