docs: update built-in components reference

vuepress · Feb 5, 2024 · 9761a9b · 9761a9b
1 parent 5531047
commit 9761a9b
Show file tree

Hide file tree

Showing 8 changed files with 91 additions and 57 deletions.
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
@@ -67,13 +67,13 @@ 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/introduction.html">Guide &gt; Introduction</RouterLink>
-  <RouterLink to="/reference/config.html#links">
+  <RouteLink to="/">Home</RouteLink>
+  <RouteLink to="/reference/config.html">Config Reference</RouteLink>
+  <RouteLink to="/guide/getting-started.html">Getting Started</RouteLink>
+  <RouteLink to="/guide/introduction.html">Guide &gt; Introduction</RouteLink>
+  <RouteLink to="/reference/config.html#links">
     Config Reference &gt; markdown.links
-  </RouterLink>
+  </RouteLink>
   <a href="https://github.com" target="_blank" rel="noopener noreferrer">
     GitHub
   </a>
@@ -91,7 +91,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 [RouteLink](../reference/components.md#routelink) 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.
 

diff --git a/docs/reference/components.md b/docs/reference/components.md
@@ -25,23 +25,54 @@
 
 - Props:
 
-  - pageKey
+  - path
     - Type: `string`
     - Required: `false`
 
 - Usage:
 
 ```md
-<Content page-key="v-xxxxxx" />
+<Content path="/path/to/page.md" />
 ```
 
 - Details:
 
   This component will render the Markdown content of a page.
 
-  The page key is the [name](https://router.vuejs.org/api/#name-2) of the page route. If the `pageKey` prop is not provided, it will render the page of current route.
+  If the `path` prop is not provided, it will render the page content of current route.
 
   This component is mainly for developing themes. You won't need it in most cases.
 
 - Also see:
-  - [Node API > Page Properties > key](./node-api.md#key)
+  - [Node API > Page Properties > path](./node-api.md#path)
+
+## RouteLink
+
+- Props:
+
+  - to
+    - Type: `string`
+    - Required: `true`
+  - active
+    - Type: `boolean`
+    - Required: `false`
+    - Default: `false`
+  - activeClass
+    - Type: `string`
+    - Required: `false`
+    - Default: `'route-link-active'`
+
+- Usage:
+
+```md
+<RouteLink to="/path/to/target-page.md">target page</RouteLink>
+<RouteLink active to="/path/to/current-page.md">current page</RouteLink>
+```
+
+- Details:
+
+  This component will render a link to the target page.
+
+  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`.
diff --git a/docs/reference/config.md b/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 the tag of internal links to [internalTag](#markdownlinksinternaltag), and add extra attributes and icon to external links.
 
   Set to `false` to disable this plugin.
 
@@ -595,15 +595,15 @@ const defaultOptions = {
 
 #### markdown.links.internalTag
 
-- Type: `'a' | 'RouterLink'`
+- Type: `'a' | 'RouteLink' | 'RouterLink'`
 
-- Default: `'RouterLink'`
+- Default: `'RouteLink'`
 
 - 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 [RouteLink](./components.md#routelink).
 
 #### markdown.links.externalAttrs
 

diff --git a/docs/reference/node-api.md b/docs/reference/node-api.md
@@ -365,19 +365,6 @@ Hello, world.
 
 ## Page Properties
 
-### key
-
-- Type: `string`
-
-- Details:
-
-  Identifier of the page.
-
-  The page key would be used as the [name](https://router.vuejs.org/api/#name-2) of the page route.
-
-- Also see:
-  - [Built-in Components > Content](./components.md#content)
-
 ### path
 
 - Type: `string`
@@ -454,7 +441,6 @@ interface PageHeader {
 
 ```ts
 interface PageData {
-  key: string
   path: string
   title: string
   lang: string

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

diff --git a/docs/zh/reference/components.md b/docs/zh/reference/components.md
@@ -25,23 +25,54 @@
 
 - Props:
 
-  - pageKey
+  - path
     - 类型： `string`
     - 是否必须： `false`
 
 - 使用：
 
 ```md
-<Content page-key="v-xxxxxx" />
+<Content path="/path/to/page.md" />
 ```
 
 - 详情：
 
   该组件会渲染页面的 Markdown 内容。
 
-  页面 Key 是页面路由的 [name](https://router.vuejs.org/zh/api/#name-2) 。如果没有传入 `pageKey` Prop ，它会渲染当前路由下的页面。
+  如果没有传入 `path` Prop ，它会渲染当前路由下的页面内容。
 
   该组件主要是为了开发主题时使用。在绝大多数情况下你不会用到它。
 
 - 参考：
-  - [Node API > Page 属性 > key](./node-api.md#key)
+  - [Node API > Page 属性 > path](./node-api.md#path)
+
+## RouteLink
+
+- Props:
+
+  - to
+    - 类型： `string`
+    - 是否必须： `true`
+  - active
+    - 类型： `boolean`
+    - 是否必须： `false`
+    - 默认值： `false`
+  - activeClass
+    - 类型： `string`
+    - 是否必须： `false`
+    - 默认值： `'route-link-active'`
+
+- 使用：
+
+```md
+<RouteLink to="/path/to/target-page.md">目标页面</RouteLink>
+<RouteLink active to="/path/to/current-page.md">当前页面</RouteLink>
+```
+
+- 详情：
+
+  该组件会渲染一个链接，用于跳转到指定页面。
+
+  如果 `active` Prop 被设置为 `true` ，那么这个链接会被额外添加一个 `activeClass` 类名。需要注意的是，这里的 active 状态并不会根据当前路由自动更新。
+
+  该组件主要是为了开发主题时使用。在绝大多数情况下你不会用到它。对于主题作者来说，我们建议你尽可能使用这个组件，而不是使用 `vue-router` 的 `<RouterLink>` 组件。
diff --git a/docs/zh/reference/config.md b/docs/zh/reference/config.md
@@ -599,7 +599,7 @@ const defaultOptions = {
 
   VuePress 内置的 markdown-it 链接插件的配置项。
 
-  它可以把站内链接转换为 `<RouterLink>` ，并且可以在站外链接上添加额外的属性和图标。
+  它可以把站内链接的 tag 转换为 [internalTag](#markdownlinksinternaltag) ，并且可以在站外链接上添加额外的属性和图标。
 
   设置为 `false` 可以禁用该插件。
 
@@ -610,13 +610,13 @@ const defaultOptions = {
 
 - 类型： `string`
 
-- 默认值： `'RouterLink'`
+- 默认值： `'RouteLink'`
 
 - 详情：
 
   内部链接所使用的标签。
 
-  默认情况下，该插件会把内部链接转换为 `<RouterLink>` 。你可以把该选项设置为 `'a'` 来禁用这个功能。
+  默认情况下，该插件会把内部链接转换为 [RouteLink](./components.md#routelink) 。
 
 #### markdown.links.externalAttrs
 

diff --git a/docs/zh/reference/node-api.md b/docs/zh/reference/node-api.md
@@ -363,19 +363,6 @@ export default {
 
 ## Page 属性
 
-### key
-
-- 类型： `string`
-
-- 详情：
-
-  该 Page 的标识。
-
-  Page Key 会被用作页面路由的 [name](https://router.vuejs.org/api/#name-2)。
-
-- 参考：
-  - [Built-in Components > Content](./components.md#content)
-
 ### path
 
 - 类型： `string`
@@ -452,7 +439,6 @@ interface PageHeader {
 
 ```ts
 interface PageData {
-  key: string
   path: string
   title: string
   lang: string