feat(client): add VPLink

docs/guide/markdown.md

@@ -62,11 +62,11 @@ Take our documentation source files as an example:
 
 ```vue
 <template>
-  <RouterLink to="/">Home</RouterLink>
-  <RouterLink to="/reference/config.html">Config Reference</RouterLink>
-  <RouterLink to="/guide/getting-started.html">Getting Started</RouterLink>
-  <RouterLink to="/guide/">Guide</RouterLink>
-  <RouterLink to="/reference/config.html#links">Config Reference &gt; markdown.links</RouterLink>
+  <VPLink to="/">Home</VPLink>
+  <VPLink to="/reference/config.html">Config Reference</VPLink>
+  <VPLink to="/guide/getting-started.html">Getting Started</VPLink>
+  <VPLink to="/guide/">Guide</VPLink>
+  <VPLink to="/reference/config.html#links">Config Reference &gt; markdown.links</VPLink>
   <a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub</a>
 </template>
 ```
@@ -82,7 +82,7 @@ Take our documentation source files as an example:
 
 **Explanation**
 
-- Internal links will be converted to `<RouterLink>` for SPA navigation.
+- Internal links will be converted to `<VPLink>` which is similar to `<RouterLink>` for SPA navigation.
 - Internal links to `.md` files will be converted to the [page route path](./page.md#routing), and both absolute path and relative path are supported.
 - External links will get `target="_blank" rel="noopener noreferrer"` attrs.
 

docs/reference/components.md

@@ -26,7 +26,7 @@
 - Props:
   - pageKey
     - Type: `string`
-    - Required: `false`
+    - Required: No`
 
 - Usage:
 
@@ -44,3 +44,24 @@
 
 - Also see:
   - [Node API > Page Properties > key](./node-api.md#key)
+
+## VPLink
+
+- Props:
+  - to
+    - Type: `string`
+    - Required: Yes
+
+- Usage:
+
+```md
+<VPLink to="/path/to/link" />
+```
+
+- Details:
+
+   This component will render an `<a>` link that has SPA navigation capabilities, and will trigger `router.push` when clicked.
+
+   Its `to` property is the link to navigate to.
+
+   This component is mainly used to replace `<RouterLink>`, which has expensive initialization. If you need to place internal links and don't care about its exact rendering href and activate state, you should use it as first choice.

docs/reference/config.md

@@ -586,7 +586,7 @@ const defaultOptions = {
 
   Options for VuePress built-in markdown-it links plugin.
 
-  It will convert internal links to `<RouterLink>`, and add extra attributes and icon to external links.
+  It will convert internal links to `<VPLink>` (similar to `<RouterLink>` with SPA navigation support), and add extra attributes and icon to external links.
 
   Set to `false` to disable this plugin.
 
@@ -595,15 +595,17 @@ const defaultOptions = {
 
 #### markdown.links.internalTag
 
-- Type: `'a' | 'RouterLink'`
+- Type: `'a' | 'RouterLink' | 'VPLink'`
 
-- Default: `'RouterLink'`
+- Default: `'VPLink'`
 
 - Details:
 
   Tag for internal links.
 
-  By default, this plugin will transform internal links to `<RouterLink>`. You can set this option to `'a'` to disable this feature.
+  By default, this plugin will transform internal links to `<VPLink>` with SPA navigation support.
+
+  You can set this option to `'RouterLink'` for standard router link with exact route resolving and active and exactActive state, or set this option to `'a'` to disable this feature.
 
 #### markdown.links.externalAttrs
 

docs/reference/plugin/toc.md

@@ -105,7 +105,7 @@ interface TocPropsOptions {
   containerClass: string
   listClass: string
   itemClass: string
-  linkTag: 'a' | 'RouterLink'
+  linkTag: 'a' | 'RouterLink' | 'VPLink'
   linkClass: string
   linkActiveClass: string
   linkChildrenActiveClass: string
@@ -122,7 +122,7 @@ const defaultOptions = {
   containerClass: 'vuepress-toc',
   listClass: 'vuepress-toc-list',
   itemClass: 'vuepress-toc-item',
-  linkTag: 'RouterLink',
+  linkTag: 'VPLink',
   linkClass: 'vuepress-toc-link',
   linkActiveClass: 'active',
   linkChildrenActiveClass: 'active',
@@ -148,18 +148,18 @@ const defaultOptions = {
       <!-- item -->
       <li class="vuepress-toc-item">
         <!-- link -->
-        <RouterLink class="vuepress-toc-link" to="#foo">Foo</RouterLink>
+        <VPLink class="vuepress-toc-link" to="#foo">Foo</VPLink>
       </li>
       <!-- item with children -->
       <li class="vuepress-toc-item">
         <!-- link (children active) -->
-        <RouterLink class="vuepress-toc-link active" to="#bar">Bar</RouterLink>
+        <VPLink class="vuepress-toc-link active" to="#bar">Bar</VPLink>
         <!-- list (children) -->
         <ul class="vuepress-toc-list">
           <!-- item -->
           <li class="vuepress-toc-item">
             <!-- link (active) -->
-            <RouterLink class="vuepress-toc-link active" to="#bar-child">Bar Child</RouterLink>
+            <VPLink class="vuepress-toc-link active" to="#bar-child">Bar Child</VPLink>
           </li>
         </ul>
       </li>

docs/zh/guide/markdown.md

@@ -63,11 +63,11 @@ VuePress 会使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来
 
 ```vue
 <template>
-  <RouterLink to="/zh/">首页</RouterLink>
-  <RouterLink to="/zh/reference/config.html">配置参考</RouterLink>
-  <RouterLink to="/zh/guide/getting-started.html">快速上手</RouterLink>
-  <RouterLink to="/zh/guide/">指南</RouterLink>
-  <RouterLink to="/zh/reference/config.html#links">配置参考 &gt; markdown.links</RouterLink>
+  <VPLink to="/zh/">首页</VPLink>
+  <VPLink to="/zh/reference/config.html">配置参考</VPLink>
+  <VPLink to="/zh/guide/getting-started.html">快速上手</VPLink>
+  <VPLink to="/zh/guide/">指南</VPLink>
+  <VPLink to="/zh/reference/config.html#links">配置参考 &gt; markdown.links</VPLink>
   <a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub</a>
 </template>
 ```
@@ -83,7 +83,7 @@ VuePress 会使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来
 
 **解释**
 
-- 内部链接会被转换为 `<RouterLink>` 以便进行 SPA 导航。
+- 内部链接会被转换为和 `<RouterLink>` 类似的 `<VPLink>` 以便进行 SPA 导航。
 - 指向 `.md` 文件的内部链接会被转换为目标页面的 [路由路径](./page.md#路由)，并且支持绝对路径和相对路径。
 - 外部链接会被添加 `target="_blank" rel="noopener noreferrer"` 属性。
 

docs/zh/reference/components.md

@@ -18,15 +18,15 @@
 
   如果一个组件在 `setup()` 中直接使用 浏览器 / DOM API ，它会导致构建过程报错，因为这些 API 在 Node.js 的环境中是无法使用的。在这种情况下，你可以选择一种方式：
 
-  - 修改这个组件，只在  `onBeforeMount()` 或 `onMounted()` Hook 中使用 浏览器 / DOM API 。
+  - 修改这个组件，只在 `onBeforeMount()` 或 `onMounted()` Hook 中使用 浏览器 / DOM API 。
   - 使用 `<ClientOnly>` 包裹这个组件。
 
 ## Content
 
-- Props:
+- 属性:
   - pageKey
     - 类型： `string`
-    - 是否必须： `false`
+    - 必要： 否
 
 - 使用：
 
@@ -44,3 +44,24 @@
 
 - 参考：
   - [Node API > Page 属性 > key](./node-api.md#key)
+
+## VPLink
+
+- 属性:
+  - to
+    - 类型： `string`
+    - 必要： 是
+
+- 使用：
+
+```md
+<VPLink to="/path/to/link" />
+```
+
+- 详情：
+
+  该组件会渲染一个拥有 SPA 导航能力的 `<a>` 链接，点击时会触发 `router.push` 行为。
+
+  它的 `to` 属性是需要导航到的链接。
+
+  该组件主要用于替代初始化开销过大的 `<RouterLink>` ，如果你需要放置内部链接且不关注准确的解析地址以及激活状态，你应该首选使用它。

docs/zh/reference/config.md

@@ -599,7 +599,7 @@ const defaultOptions = {
 
   VuePress 内置的 markdown-it 链接插件的配置项。
 
-  它可以把站内链接转换为 `<RouterLink>` ，并且可以在站外链接上添加额外的属性和图标。
+  它可以把站内链接转换为 `<VPLink>` (类似于 `<RouterLink>`，提供 SPA 导航) ，并且可以在站外链接上添加额外的属性和图标。
 
   设置为 `false` 可以禁用该插件。
 
@@ -608,15 +608,17 @@ const defaultOptions = {
 
 #### markdown.links.internalTag
 
-- 类型： `string`
+- 类型： `'a' | 'RouterLink' | 'VPLink'`
 
-- 默认值： `'RouterLink'`
+- 默认值： `'VPLink'`
 
 - 详情：
 
   内部链接所使用的标签。
 
-  默认情况下，该插件会把内部链接转换为 `<RouterLink>` 。你可以把该选项设置为 `'a'` 来禁用这个功能。
+  默认情况下，该插件会把内部链接转换为 `<VPLink>`，以提供 SPA 导航。
+
+  你可以将该选项设置为 `'RouterLink'` 来渲染为带有准确路由解析以及激活和准确激活状态的 `<RouterLink>`。也可以将该选项设置为 `'a'` 来禁用这个功能。
 
 #### markdown.links.externalAttrs
 

docs/zh/reference/plugin/toc.md

@@ -105,7 +105,7 @@ interface TocPropsOptions {
   containerClass: string
   listClass: string
   itemClass: string
-  linkTag: 'a' | 'RouterLink'
+  linkTag: 'a' | 'RouterLink' | 'VPLink'
   linkClass: string
   linkActiveClass: string
   linkChildrenActiveClass: string
@@ -122,7 +122,7 @@ const defaultOptions = {
   containerClass: 'vuepress-toc',
   listClass: 'vuepress-toc-list',
   itemClass: 'vuepress-toc-item',
-  linkTag: 'RouterLink',
+  linkTag: 'VPLink',
   linkClass: 'vuepress-toc-link',
   linkActiveClass: 'active',
   linkChildrenActiveClass: 'active',
@@ -148,18 +148,18 @@ const defaultOptions = {
       <!-- item -->
       <li class="vuepress-toc-item">
         <!-- link -->
-        <RouterLink class="vuepress-toc-link" to="#foo">Foo</RouterLink>
+        <VPLink class="vuepress-toc-link" to="#foo">Foo</VPLink>
       </li>
       <!-- item with children -->
       <li class="vuepress-toc-item">
         <!-- link (children active) -->
-        <RouterLink class="vuepress-toc-link active" to="#bar">Bar</RouterLink>
+        <VPLink class="vuepress-toc-link active" to="#bar">Bar</VPLink>
         <!-- list (children) -->
         <ul class="vuepress-toc-list">
           <!-- item -->
           <li class="vuepress-toc-item">
             <!-- link (active) -->
-            <RouterLink class="vuepress-toc-link active" to="#bar-child">Bar Child</RouterLink>
+            <VPLink class="vuepress-toc-link active" to="#bar-child">Bar Child</VPLink>
           </li>
         </ul>
       </li>

ecosystem/plugin-external-link-icon/tests/node/externalLinkIconPlugin.spec.ts

@@ -39,7 +39,7 @@ describe('@vuepress/plugin-external-link-icon > node > externalLinkIconPlugin',
         '<a href="//github.com" target="_blank" rel="noopener noreferrer">github<ExternalLinkIcon/></a>',
         '<a href="https://github.com" target="_blank" rel="noopener noreferrer">https://github.com<ExternalLinkIcon/></a>',
         '<a href="http://github.com" target="_blank" rel="noopener noreferrer">http://github.com<ExternalLinkIcon/></a>',
-        '<RouterLink to="foo.html">foo</RouterLink>',
+        '<VPLink to="foo.html">foo</VPLink>',
       ]
         .map((a) => `<p>${a}</p>`)
         .join('\n') + '\n',
@@ -66,7 +66,7 @@ describe('@vuepress/plugin-external-link-icon > node > externalLinkIconPlugin',
         '<a href="//github.com" target="_self" rel="noopener noreferrer">github</a>',
         '<a href="https://github.com" target="_self" rel="noopener noreferrer">https://github.com</a>',
         '<a href="http://github.com" target="_self" rel="noopener noreferrer">http://github.com</a>',
-        '<RouterLink to="foo.html">foo</RouterLink>',
+        '<VPLink to="foo.html">foo</VPLink>',
       ]
         .map((a) => `<p>${a}</p>`)
         .join('\n') + '\n',
@@ -87,7 +87,7 @@ describe('@vuepress/plugin-external-link-icon > node > externalLinkIconPlugin',
         '<a href="//github.com" target="_blank" rel="noopener noreferrer">github</a>',
         '<a href="https://github.com" target="_blank" rel="noopener noreferrer">https://github.com</a>',
         '<a href="http://github.com" target="_blank" rel="noopener noreferrer">http://github.com</a>',
-        '<RouterLink to="foo.html">foo</RouterLink>',
+        '<VPLink to="foo.html">foo</VPLink>',
       ]
         .map((a) => `<p>${a}</p>`)
         .join('\n') + '\n',

ecosystem/plugin-toc/src/client/components/Toc.ts

@@ -1,8 +1,8 @@
 import { usePageData } from '@vuepress/client'
 import type { PageHeader } from '@vuepress/client'
-import { computed, defineComponent, h, toRefs } from 'vue'
+import { computed, defineComponent, h, resolveComponent, toRefs } from 'vue'
 import type { PropType, VNode } from 'vue'
-import { RouterLink, useRoute } from 'vue-router'
+import { useRoute } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
 import type { TocPropsOptions } from '../../shared/index.js'
 
@@ -34,26 +34,26 @@ const renderLink = (
     linkClass.push(options.linkChildrenActiveClass)
   }
 
-  if (options.linkTag === 'RouterLink') {
+  if (options.linkTag === 'a') {
     return h(
-      RouterLink,
+      'a',
       {
-        to: hash,
+        href: hash,
         class: linkClass,
         ariaLabel: header.title,
       },
-      () => header.title,
+      header.title,
     )
   }
 
   return h(
-    'a',
+    resolveComponent(options.linkTag),
     {
-      href: hash,
+      to: hash,
       class: linkClass,
       ariaLabel: header.title,
     },
-    header.title,
+    () => header.title,
   )
 }
 
@@ -123,7 +123,7 @@ export const Toc = defineComponent({
       containerClass: 'vuepress-toc',
       listClass: 'vuepress-toc-list',
       itemClass: 'vuepress-toc-item',
-      linkTag: 'RouterLink',
+      linkTag: 'VPLink',
       linkClass: 'vuepress-toc-link',
       linkActiveClass: 'active',
       linkChildrenActiveClass: 'active',

ecosystem/plugin-toc/src/shared/types.ts

@@ -3,7 +3,7 @@ export interface TocPropsOptions {
   containerClass: string
   listClass: string
   itemClass: string
-  linkTag: 'a' | 'RouterLink'
+  linkTag: 'a' | 'RouterLink' | 'VPLink'
   linkClass: string
   linkActiveClass: string
   linkChildrenActiveClass: string