永久链接

永久链接

VitePress 默认以 Markdown 文件路径作为链接访问，这会存在一个缺陷，当文件路径改变时，链接也会改变（再访问原来链接就会 404），在配置侧边栏、导航栏、各个文档链接引用、分享等场景时造成很大困扰。

因此需要给文件添加一个 永久链接，无论文件路径改变，访问链接不会改变。

Teek 使用 vitepress-plugin-permalink 来实现永久链接功能。

插件已经内置到 Teek 中，你只需要在 Markdown 文件的 frontmatter 中添加如下内容：

---
permalink: /guide/quickstart
---

这样就可以通过 /guide/quickstart 访问该页面了。

如果您不需要永久链接功能，请不配置 permalink 或者直接禁用该插件：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    permalink: false, // 禁用该插件
  },
});

永久链接方式

vitepress-plugin-permalink 插件提供两种方式实现永久链接：

1. Proxy 方式
2. Rewrites 方式

Proxy 方式不会影响文件路径，而是在访问文件路径时，通过代理（拦截）将其转换 Permalink，因此既可以通过文件路径访问，也可以通过 Permalink 访问。

Rewrites 方式在项目运行或者构建时，通过改变文件路径达到永久链接功能，你可以在构建的 dist 文件夹查看修改后的文件路径。

两者只能二选一，如果都配置，则以 Rewrites 方式为主。

Teek 默认为 Proxy 方式，如果替换为 Rewrites 方式，在 config.mts 里添加如下代码：

import { defineConfig } from "vitepress";
import { createRewrites } from "vitepress-theme-teek/config";

export default defineConfig({
  rewrites: createRewrites(/** options */),
});

createRewrites 函数支持除了传入 vitepress-plugin-permalink 的 配置项，也支持额外传入两个配置项：

• srcDir：VitePress 的 srcDir，默认为 .，即当前项目的绝对目录
• locales：VitePress 的 locales

如果没有传入配置项，则默认为从文档的根目录进行扫描。

侧边栏方式

Teek 使用 vitepress-plugin-sidebar-resolve 来实现自动生成侧边栏功能。

默认情况下，Teek 按照项目的目录结构生成侧边栏，如果你修改永久链接方式为 rewrites，则目录结构作为侧边栏将会失效，因此需要手动开启 rewrites 生成侧边栏。

通过 resolveRule 配置项来配置侧边栏生成规则：

• 当 resolveRule 为 filePath，则按照本地文件路径生成侧边栏
• 当 resolveRule 为 rewrites，则按照 rewrites 结果生成侧边栏

import { defineConfig } from "vitepress";
import { createRewrites } from "vitepress-theme-teek/config";

export default defineConfig({
  rewrites: createRewrites(),
  vite: {
    plugins: [
      Sidebar({
        resolveRule: "rewrites",
      }),
    ],
  },
});

如果 resolveRule 为 rewrites，但是没有 rewrites 配置，则按照 filePath 配置生成侧边栏。

什么是 rewrites

rewrites 是什么？，请看 VitePress 的 路由重写 描述。

这里简单说下个人理解，filePath 称之为 本地文件路径，rewrites 称之为 运行文件路径。

本地文件路径通俗易懂，那什么是运行文件路径？

我们访问的 VitePress 文档的链接地址就是 运行文件路径。VitePress 启动后，默认会将本地文件路径当作运行文件路径，但是我们可以通过 rewrites 将本地文件路径重写为新的文件路径，新的文件路径就会取代本地文件路径成为运行文件路径。

假设文件 quick-start.md 在本地路径为 guide/quick-start.md，在 rewrites 中添加如下配置：

import { defineConfig } from "vitepress";

export default defineConfig({
  rewrites: {
    "guide/quick-start.md": "/config/quick.md",
  },
});

此时该文件的运行文件路径为 /config/quick 而不是 /guide/quick-start。