docs: add route related docs (#26)

Co-authored-by: meteorlxy <[email protected]>

docs/.vuepress/configs/sidebar/en.ts

@@ -39,6 +39,7 @@ export const sidebarEn: SidebarConfig = {
         '/advanced/cookbook/making-a-theme-extendable.md',
         '/advanced/cookbook/passing-data-to-client-code.md',
         '/advanced/cookbook/markdown-and-vue-sfc.md',
+        '/advanced/cookbook/resolving-routes.md',
       ],
     },
   ],

docs/.vuepress/configs/sidebar/zh.ts

@@ -39,6 +39,7 @@ export const sidebarZh: SidebarConfig = {
         '/zh/advanced/cookbook/making-a-theme-extendable.md',
         '/zh/advanced/cookbook/passing-data-to-client-code.md',
         '/zh/advanced/cookbook/markdown-and-vue-sfc.md',
+        '/zh/advanced/cookbook/resolving-routes.md',
       ],
     },
   ],

docs/advanced/cookbook/resolving-routes.md

@@ -0,0 +1,50 @@
+# Resolving Routes
+
+## Getting all routes
+
+You can make use of [useRoutes](../../reference/client-api.md#useroutes) to get all routes information.
+
+The return value of `useRoutes` is a Ref object containing all routes. The keys are route paths of each route, and the values are the corresponding route information.
+
+```ts
+import { useRoutes } from 'vuepress/client'
+
+const routes = useRoutes()
+// {
+// '/': { meta: { title: 'Home' }, loader: HomePageLoader },
+// '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader },
+// ...
+// }
+
+const routePaths = computed(() => Object.keys(routes.value))
+// => ['/‘, '/404.html', '/foo/', '/bar/', ...]
+```
+
+## Resolving route path
+
+You can make use of [resolveRoutePath](../../reference/client-api.md#resolveroutepath) to resolve the route path of the given link.
+
+`resolveRoutePath` receives a link and an optional base path, and returns the resolved route path:
+
+```ts
+import { resolveRoutePath } from 'vuepress/client'
+
+const routePath = resolveRoutePath('/foo/') // => '/foo/'
+const routePath = resolveRoutePath('baz.html', '/foo/bar.html') // => '/foo/baz.html'
+```
+
+## Resolving route information
+
+You can make use of [resolveRoute](../../reference/client-api.md#resolveroute) to resolve route information for a given link.
+
+`resolveRoute` receives a link and an optional base path, and returns the resolved route information:
+
+```ts
+import { resolveRoute } from 'vuepress/client'
+
+const route = resolveRoute('/foo/') // => { notFound: false, path: '/foo/', meta: { title: 'Foo' }, loader: FooPageLoader }
+const route = resolveRoute('baz.html', '/foo/bar.html') // => { notFound: false, path: '/foo/baz.html', meta: { title: 'Baz' }, loader: BazPageLoader }
+const route = resolveRoute('/not-exist.html') // => { notFound: true, path: '/not-exist.html', meta: { title: 'Not Found' }, loader: NotFoundPageLoader }
+```
+
+There is a `notFound` field in the returned information, which is used to indicate whether a corresponding route exists for a given path. When the route does not exist, the `notFound` field would be `true`, the `path` field would be the normalized path, and the `meta` and `loader` fields would point to the default 404 page.

docs/guide/migration.md

@@ -415,7 +415,7 @@ Some major breaking changes:
 - `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/plugins/theme-data.html) plugin and its `useThemeData` composition API.
 - Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](https://ecosystem.vuejs.press/plugins/palette.html) may help.
 - Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/plugins/prismjs.html) or [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/plugins/shiki.html), or implement syntax highlighting in your own way.
-- For scalability concerns, `this.$site.pages` is not available any more.
+- For scalability concerns, `this.$site.pages` is not available any more. See [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) for how to retrieve pages data in v2.
 
 For more detailed guide about how to write a theme in v2, see [Advanced > Writing a Theme](../advanced/theme.md).
 

docs/reference/client-api.md

@@ -73,6 +73,17 @@ const {
 
   The value is the `lang` property of the page data.
 
+## useRoutes
+
+- Details:
+
+  Returns the routes ref object.
+
+  The value is the `routes` property of the site data.
+
+- Also see:
+  - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md)
+
 ### useRouteLocale
 
 - Details:
@@ -106,6 +117,24 @@ const {
 - Also see:
   - [Advanced > Cookbook > Usage of Client Config](../advanced/cookbook/usage-of-client-config.md)
 
+### resolveRoute
+
+- Details:
+
+  Parses the route of the given link.
+
+- Also see:
+  - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md)
+
+## resolveRoutePath
+
+- Details:
+
+  Parses the route path of the given link.
+
+- Also see:
+  - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md)
+
 ### withBase
 
 - Details:

docs/zh/advanced/cookbook/resolving-routes.md

@@ -0,0 +1,50 @@
+# 解析路由
+
+## 获取全部路由
+
+在开发主题和插件时，你可能希望获取所有页面的信息。通过 [useRoutes](../../reference/client-api.md#useroutes) 就可以获取所有页面的路由记录。
+
+`useRoutes` 的返回值是一个包含了所有路由信息的 Ref 对象。其属性是每条路由的路由路径，对应的值是路径的路由信息。
+
+```ts
+import { useRoutes } from 'vuepress/client'
+
+const routes = useRoutes()
+// {
+//   '/': { meta: { title: 'Home' }, loader: HomePageLoader },
+//   '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader },
+//   ...
+// }
+
+const routePaths = computed(() => Object.keys(routes.value))
+// => [’/‘, '/404.html', '/foo/', '/bar/', ...]
+```
+
+## 解析路由地址
+
+你可以使用 [resolveRoutePath](../../reference/client-api.md#resolveroutepath) 来解析给定的链接对应的路由路径。
+
+`resolveRoutePath` 接收一个链接地址和一个可选的基础路径，返回一个解析后的路由地址:
+
+```ts
+import { resolveRoutePath } from 'vuepress/client'
+
+const routePath = resolveRoutePath('/foo/') // => '/foo/'
+const routePath = resolveRoutePath('baz.html', '/foo/bar.html') // => '/foo/baz.html'
+```
+
+## 解析路由信息
+
+你可以使用 [resolveRoute](../../reference/client-api.md#resolveroute) 来解析给定的链接对应的路由信息。
+
+`resolveRoute` 接收一个链接地址和一个可选的基础路径，返回一个解析后的路由信息:
+
+```ts
+import { resolveRoute } from 'vuepress/client'
+
+const route = resolveRoute('/foo/') // => { notFound: false, path: '/foo/', meta: { title: 'Foo' }, loader: FooPageLoader }
+const route = resolveRoute('baz.html', '/foo/bar.html') // => { notFound: false, path: '/foo/baz.html', meta: { title: 'Baz' }, loader: BazPageLoader }
+const route = resolveRoute('/not-exist.html') // => { notFound: true, path: '/not-exist.html', meta: { title: 'Not Found' }, loader: NotFoundPageLoader }
+```
+
+路由信息中存在一个 `notFound` 字段，用于标识给定的路径是否存在对应的路由。当路由不存在时，返回值中的 `notFound` 字段为 `true`，其 `path` 字段为规范化后的路径，而 `meta` 和 `loader` 字段则会指向默认的 404 页面。

docs/zh/guide/migration.md

@@ -417,7 +417,7 @@ v1 的主题和插件和 v2 并不兼容。
 - `themeConfig` 已经从用户配置和站点数据中移除。如果你想要像 v1 一样通过 `this.$site.themeConfig` 来访问 `themeConfig` ，我们现在建议使用 [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/zh/plugins/theme-data.html) 插件和它提供的 Composition API `useThemeData` 。
 - Stylus 不再是默认的 CSS 预处理器，并且 Stylus 调色板系统不再被默认支持。如果你仍然想要使用和 v1 类似的调色板系统，可以使用 [@vuepress/plugin-palette](https://ecosystem.vuejs.press/zh/plugins/palette.html) 。
 - 由 Prism.js 提供的 Markdown 代码块的语法高亮不再被默认支持。你可以选择使用 [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/zh/plugins/prismjs.html) 或 [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/plugin/shiki.html) ，或者用你自己的方式实现语法高亮。
-- 考虑到可扩展性， `this.$site.pages` 不再可用。
+- 考虑到可扩展性， `this.$site.pages` 不再可用。查看 [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) 了解如何在 v2 中获取页面的数据。
 
 你可以参考 [深入 > 开发主题](../advanced/theme.md) 来了解如何开发一个 v2 主题。
 

docs/zh/reference/client-api.md

@@ -73,6 +73,17 @@ const {
 
   它的值是页面数据的 `lang` 属性。
 
+### useRoutes
+
+- 详情：
+
+  返回所有路由的 Ref 对象。
+
+  它的值是站点数据的路由信息。
+
+- 参考：
+  - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md)
+
 ### useRouteLocale
 
 - 详情：
@@ -106,6 +117,24 @@ const {
 - 参考：
   - [深入 > Cookbook > 客户端配置的使用方法](../advanced/cookbook/usage-of-client-config.md)
 
+### resolveRoute
+
+- 详情：
+
+  解析给定链接对应的路由
+
+- 参考：
+  - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md)
+
+## resolveRoutePath
+
+- 详情：
+
+  解析给定链接对应的路由路径
+
+- 参考：
+  - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md)
+
 ### withBase
 
 - 详情：