---
date: 2025-03-25 01:24:59
title: vitepress-plugin-link使用
permalink: /pages/53ad43
tags:
  - 插件
author:
  name: 华总
  link: https://xiaoying.org.cn
categories:
  - 工具类
  - 插件

---

# vitepress-plugin-link

## github地址

::: navCard  2
```yaml
- name: vitepress-plugin-link
  desc: 这是一个适用于 vitepress的 Vite 插件，在vitepress启动后读取 markdown 文档 frontmatter的 permalink。
  img: https://img.xiaoying.org.cn/img/202503231752583.png
  link: https://github.com/liyao52033/vitepress-plugin-link
  badge: vitepress插件
  badgeType: tip
```
:::

## ✨ 特性

- 🚀🚀 支持给 markdown 文档设置唯一的访问 **永久链接**，不再因为 markdown 文档路径移动而导致访问地址发生变化
- 🚀 读取 markdown 文档 `frontmatter` 的 `permalink`，挂载到 `themeConfig.permalinks`
- 🚀 提供 `usePermalink` hooks 函数拓展 `router` 方法，支持 `router.push(href)` 跳转到永久链接或实际的文件路径
- 🚀 支持 locales 国际化，自动给 **永久链接** 添加语言前缀，不同语言的永久链接不会重复
- 🚀 支持 rewrite 路由重写，最终得到的文档路径是 rewrite 路由重写后的路径
- 🚀 **永久链接** 支持导航栏激活高亮

## 安装

安装 `vitepress-plugin-link` 插件

::: code-group

```sh [npm]
npm install vitepress-plugin-link -D
```

```sh [yarn]
yarn add vitepress-plugin-plink -D
```

```sh [pnpm]
pnpm i vitepress-plugin-link -D
```

:::


1、添加 `vitepress-plugin-link` 插件到 `.vitepress/config.ts`

```typescript
import Permalink from "vitepress-plugin-link";

export default defineConfig({
  vite: {
    plugins: [Permalink({
      path: "docs",
    })],
  },
});
```

2、在`theme/layout/MyLayout.vue`开启监听, 插件使用了onBeforeMount等方法，必须在setUp中执行。
```vue 
<script setup lang="ts">
import DefaultTheme from 'vitepress/theme'
const { Layout } = DefaultTheme
import NotFound from "../components/NotFound.vue"; // 自定义的404组件

import usePermalink from "vitepress-plugin-link/usePermalink";
usePermalink().startWatch();


 /**
   * vitepress-plugin-link 插件在 onBeforeMount 里根据自定义 URL 寻找对应的文档进行加载，但是 Vitepress 初始化页面在 ``onBeforeMount之前执行，因此需要延迟时间来等待vitepress-plugin-link` 插件执行完成，于是需要404 页面延迟加载时间，单位为毫秒
   */
onMounted(() => {
  setTimeout(() => {
    isShow.value = true
  }, 200) // 可调整延迟时间（单位：毫秒）
})
</script>

<template>
  <Layout>
    // 插入你的插槽...
   <template #not-found>
      <ClientOnly>
          <NotFound  v-if="isShow"/>
      </ClientOnly>
  </template>
  </Layout>
</template>
```

3、`.vitepress/theme/index.ts`引用新的布局

```typescript
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  extends: DefaultTheme,
  // 使用注入插槽的包装组件覆盖 Layout
  Layout: MyLayout
}

```

> 说明：该插件仅限项目启动时生效，已改动或新添加的 markdown 需要重启项目才能生效。

插件默认忽略 `["node_modules", "dist", ".vitepress", "public"]` 目录下的文件，且只扫描 markdown 文档。

## 🛠️ Options

| name       | description                           | type       | default                        |
| ---------- | ------------------------------------- | ---------- | ------------------------------ |
| ignoreList | 忽略的文件/文件夹列表，支持正则表达式 | `string[]` | `[]`                           |
| path       | 指定扫描的根目录                      | `string`   | `vitepress` 的 `srcDir` 配置项 |

## ❗ Warning

插件的 `usePermalink` 函数使用了 `router.onAfterRouteChange` 方法，如果你也需要使用该方法，请按照下面格式进行拓展：

```typescript
import { useRouter } from "vitepress";

const router = useRouter();

const initRoute = () => {
  const selfOnAfterRouteChange = router.onAfterRouteChange;
  // 路由切换后的回调
  router.onAfterRouteChange = (href: string) => {
    // 调用可能已有的函数
    selfOnAfterRouteChange?.(href);

    // 调用自己的函数
    myFunction();
  };
};

const myFunction = () => {
  /* */
};
```

假设项目的目录结构如下：

```text
.
├─ docs                # 项目根目录
│  ├─ guide
│  │  └─ api.md
```

`api.md` 内容如下：

```yaml
---
permalink: /guide-api
---
```

- 访问 `/guide/api.html` 可以进入文档页面，这是 vitepress 的自带功能。**如果文件路径发生改变，访问链接也随着改变**
- 访问 `/guide-api` 可以进入文档页面，这是插件的实现功能。**不会随着文件路径变化而改变**

永久链接是唯一的，如果出现两个一样的永久链接，则后面的永久链接覆盖前面的，但不影响 vitepress 自带访问路径。

如果永久链接不生效，代表 `usePermalink().startWatch()` 并没有被执行，请在注册 vitepress 或者任意主题前加载该函数，如何注册请看 ([扩展默认主题 | VitePress](https://vitepress.dev/zh/guide/extending-default-theme#layout-slots))

## 📘 TypeScript

### 🛠️ Options

```typescript
export interface PermalinkOption {
  /**
   * 忽略的文件/文件夹列表，支持正则表达式
   *
   * @default []
   */
  ignoreList?: Array<RegExp | string>;
  /**
   * 文章所在的目录，基于 package.json 所在目录，开头不需要有 /
   * @default 'vitepress 的 srcDir 配置项'
   */
  path?: string;
}
```