Merge branch 'main' into theme-hope

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

@@ -33,6 +33,7 @@ export const enSidebar = sidebar({
         'making-a-theme-extendable',
         'passing-data-to-client-code',
         'markdown-and-vue-sfc',
+        'resolving-routes',
       ],
     },
   ],

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

@@ -33,6 +33,7 @@ export const zhSidebar = sidebar({
         'making-a-theme-extendable',
         'passing-data-to-client-code',
         'markdown-and-vue-sfc',
+        'resolving-routes',
       ],
     },
   ],

docs/README.md

@@ -34,6 +34,6 @@ features:
     details: Flexible plugin API, allowing plugins to provide lots of plug-and-play features for your site.
   - title: Bundlers
     icon: fa6-solid:boxes-packing
-    details: Default bundler is Vite, while Webpack is also supported. Choose the one you like!
+    details: Recommended bundler is Vite, while Webpack is also supported. Choose the one you like!
 footer: MIT Licensed | Copyright © 2018-present VuePress Community | Theme by <a href="https://theme-hope.vuejs.press">vuepress-theme-hope</a>
 ---

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

@@ -419,7 +419,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

@@ -77,6 +77,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:
@@ -110,6 +121,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/reference/components.md

@@ -4,6 +4,84 @@ icon: fa6-solid:puzzle-piece
 
 # Built-in Components
 
+## AutoLink
+
+- Props:
+
+  - config
+    - Type: `AutoLinkConfig`
+    - Required: `true`
+
+```ts
+interface AutoLinkConfig {
+  /**
+   * Pattern to determine if the link should be active, which has higher priority than `exact`
+   */
+  activeMatch?: string | RegExp
+
+  /**
+   * The `aria-label` attribute
+   */
+  ariaLabel?: string
+
+  /**
+   * Whether the link should be active only if the url is an exact match
+   */
+  exact?: boolean
+
+  /**
+   * URL of the auto link
+   */
+  link: string
+
+  /**
+   * The `rel` attribute
+   */
+  rel?: string
+
+  /**
+   * The `target` attribute
+   */
+  target?: string
+
+  /**
+   * Text of the auto link
+   */
+  text: string
+}
+```
+
+- Usage:
+
+```md
+<AutoLink :config="autoLinkConfig" />
+
+<AutoLink :config="autoLinkConfig">
+  default slot
+</AutoLink>
+
+<AutoLink :config="autoLinkConfig">
+  <template #before>before slot</template>
+  <template #after>after slot</template>
+</AutoLink>
+
+<AutoLink :config="autoLinkConfig">
+  <template v-slot="config">{{ config.text }}</template>
+</AutoLink>
+
+<AutoLink :config="autoLinkConfig">
+  <template #before="config">{{ config.text }}</template>
+</AutoLink>
+```
+
+- Details:
+
+  This component will automatically render internal link as `<RouteLink>`, and render external link as `<a>`. It will also add necessary attributes correspondingly.
+
+  You can make use of the `before` and `after` slots to render content before and after the text. Also, you can use the `default` slot to render the text (default text is `config.text`).
+
+  This component is mainly for developing themes. Users won't need it in most cases. For theme authors, it's recommended to use this component to render links that could be either internal or external.
+
 ## ClientOnly
 
 - Usage:
@@ -77,4 +155,4 @@ icon: fa6-solid:puzzle-piece
 
   If the `active` prop is set to `true`, the link will have an extra `activeClass`. Notice that the active status won't be updated automatically when the route changes.
 
-  This component is mainly for developing themes. You won't need it in most cases. For theme authors, it's recommended to use this component instead of the `<RouterLink>` component from `vue-router`.
+  This component is mainly for developing themes. Users won't need it in most cases. For theme authors, it's recommended to use this component to render internal links instead of the `<RouterLink>` component from `vue-router`.

docs/reference/config.md

@@ -374,11 +374,9 @@ Since VuePress will load temp files during dev and build, the temp directory sho
 ```ts
 const defaultOptions = {
   level: [1, 2, 3, 4, 5, 6],
-  permalink: anchorPlugin.permalink.ariaHidden({
+  permalink: anchorPlugin.permalink.headerLink({
     class: 'header-anchor',
-    symbol: '#',
-    space: true,
-    placement: 'before',
+    safariReaderFix: true,
   }),
 }
 ```

docs/reference/frontmatter.md

@@ -113,14 +113,16 @@ layout: CustomLayout
 
 ## permalink
 
-- Type: `string`
+- Type: `string | null`
 
 - Details:
 
   Permalink for the page.
 
   This will override the default route path that determined by the file path of the page.
 
+  When it is set to `null`, the permalink of the page will be disabled.
+
 - Also see:
   - [Frontmatter > permalinkPattern](#permalinkpattern)
   - [Guide > Page > Routing](../guide/page.md#routing)

docs/zh/README.md

@@ -34,6 +34,6 @@ features:
     details: 灵活的插件API，使得插件可以为你的站点提供许多即插即用的功能。
   - title: 打包工具
     icon: fa6-solid:boxes-packing
-    details: 默认的打包工具是 Vite ，也同样支持 Webpack 。选一个你喜欢的来使用吧！
+    details: 推荐的打包工具是 Vite ，但也同样支持使用 Webpack 。选一个你喜欢的来使用吧！
 footer: MIT 协议 | 版权所有 © 2018-至今 VuePress 社区 | 使用 <a href="https://theme-hope.vuejs.press/zh/">vuepress-theme-hope</a> 主题
 ---

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

@@ -421,7 +421,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

@@ -77,6 +77,17 @@ const {
 
   它的值是页面数据的 `lang` 属性。
 
+### useRoutes
+
+- 详情：
+
+  返回所有路由的 Ref 对象。
+
+  它的值是站点数据的路由信息。
+
+- 参考：
+  - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md)
+
 ### useRouteLocale
 
 - 详情：
@@ -110,6 +121,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
 
 - 详情：