One

主题

Vite 插件 ​

Vitepress 处于 Vite 环境下，因此天然支持 Vite 插件。

Teek 有过一个想法，那就是将所有功能完全插件化，通过 NPM 下载各个插件来合并成主题：

  • 目录页插件
  • 归档页插件
  • 文章信息插件
  • Footer 插件
  • ...

这完全是可行的，每个插件都是独立的，支持任何 Vitepress 项目。

但是目前没有太多精力去实现这个计划，您可以通过 Teek 的按需引入功能（等价于下载插件），来加载自己需要的功能。

在了解 Vite 插件实现之前，建议您先去 Vite 官方文档 了解什么是 Vite。

下面介绍在 Vitepress 中自定义 Vite 插件的场景。

Vite 插件基础模板 ​

首先介绍 Vite 插件的基础模板：

ts
import type { Plugin } from "vite";

interface Options {
  // ...
}

export default function VitePluginVitePressTemplate(option: Options = {}): Plugin {
  return {
    name: "vite-plugin-vitepress-template",
    // ...
  };
}

Vite 插件本质是一个函数，需要返回一个对象，对象的各个 Key 就是 Vite 提供的钩子，比如 transform、config 等，我们需要识别这些钩子分别执行了哪部分逻辑，这样才能针对性的实现自己的功能。

Vite 提供了哪些钩子请看官网 插件 API。

扫描项目文件 ​

如果您使用了 Teek 主题，那么在项目启动时，终端会打印：

sh
Injected Sidebar Data Successfully. 注入侧边栏数据成功!
Injected Permalinks Data Successfully. 注入永久链接数据成功!
Injected DocAnalysisInfo Data Successfully. 注入文档分析数据成功!
Injected Catalogues Data Successfully. 注入目录页数据成功!
Injected posts Data Successfully. 注入 posts 数据成功!

每一行都是一个 Vite 插件输出的内容，这些插件都是去扫描项目的 Markdown 文件，然后生成数据并注入到 Vitepress 的 themeConfig 中。

扫描项目文件的目的有如下场景：

  • 生成侧边栏：根据 Markdown 文件路径生成侧边栏数据
  • 解析 Markdown 文档的 frontmatter 来生成文章信息，或给 Markdown 文件自动添加 frontmatter
  • 解析 Markdown 文档的内容，生成站点信息功能（总字数、文章字数、阅读时长等）
  • ...

这里需要用到 Vite 提供的 config 钩子，在解析 Vitepress 配置前会调用该钩子，因此我们在这个钩子里执行扫描项目文件的逻辑，最后将数据注入到 Vitepress 的 themeConfig 中。

ts
import type { Plugin } from "vite";

interface Options {
  // ...
}

export default function VitePluginVitePressDemo(option: Options = {}): Plugin & { name: string } {
  return {
    name: "vitepress-plugin-demo",
    config(config: any) {
      // 获取 themeConfig 配置
      const {
        site: { themeConfig = {} },
        srcDir,
      } = config.vitepress;

      // 使用 node API 扫描项目文件，项目文件的根路径为 srcDir
      const data = scanProjectFiles(srcDir);

      themeConfig.demo = data;
    },
  };
}

const scanProjectFiles = (srcDir: string) => {};

这里就不详细介绍 scanProjectFiles 的逻辑，您可以阅读 Teek 的 Vite 插件源码来了解具体实现。

加载功能组件 ​

开头说的可以将各个功能完全插件化，就是利用插件来往 Vitepress 的插槽中插入组件。

Vite 提供的 load、transform、resolveId 等钩子，是在访问某个资源的时候被调用，比如在浏览器访问某个页面时，我们可以通过这些钩子拦截到页面的代码，然后进行内容加工再返回给浏览器渲染。

因此当进入 Vitepress 页面时，我们可以拦截 Vitepress 的 Layout 组件，然后将自己实现的组件插入到插槽中，最后返回给浏览器渲染。

Vitepress 提供了哪些插槽请看 布局插槽。

比如自定义一个组件插入到 Layout 的 layout-top 插槽中。

ts
const isESM = () => {
  return typeof __filename === "undefined" || typeof __dirname === "undefined";
};

const getDirname = () => {
  return isESM() ? dirname(fileURLToPath(import.meta.url)) : __dirname;
};

// 插件名
const componentName = "MyComponent";
const componentFile = `${componentName}.vue`;
const aliasComponentFile = `${getDirname()}/components/${componentFile}`;
const virtualModuleId = "virtual:my-component-option";
const resolvedVirtualModuleId = `\0${virtualModuleId}`;

export function VitePluginVitePressMyNotFound(option: NotFoundOption = {}): Plugin & { name: string } {
  return {
    name: "vite-plugin-vitepress-my-not-found",
    config() {
      return {
        resolve: {
          alias: {
            [`./${componentFile}`]: aliasComponentFile,
          },
        },
      };
    },
    resolveId(id: string) {
      if (id === virtualModuleId) return resolvedVirtualModuleId;
    },
    load(id: string) {
      // 使用虚拟模块将 option 传入组件里
      if (id === resolvedVirtualModuleId) return `export default ${JSON.stringify(option)}`;

      // 在 Layout.vue 插槽插入自定义组件
      if (id.endsWith("vitepress/dist/client/theme-default/Layout.vue")) {
        // 读取原始的 Vue 文件内容
        const code = readFileSync(id, "utf-8");

        // 插入自定义组件
        const slotName = "layout-top";
        const slotPosition = `<slot name="${slotName}" />`;
        const setupPosition = '<script setup lang="ts">';

        return code
          .replace(slotPosition, `${slotPosition}<${componentName} />`);
          .replace(setupPosition, `${setupPosition}\nimport ${componentName} from './${componentFile}'`);
      }
    },
  };
}
vue
<script setup lang="ts" name="MyComponent">
// @ts-ignore
import option from "virtual:my-component-option";

const { label = "myComponent" } = { ...option };
</script>

<template>
  <div>{{ label }}</div>
</template>

插件通过虚拟模块将 option 配置传入到 virtual:my-component-option 中，因此可以在组件里引入。虚拟模块的内容请看 Vite 官网 虚拟模块相关说明

上面 index.ts 给出的代码模板具有通用性，你只需要：

  • 将 const componentName = "MyComponent"; 改为要插入的组件名
  • 将 const slotName = "layout-top"; 改为要插入的插槽名

为什么不用 transform 钩子？

transform 钩子返回的资源内容已经过 rollup 编译过，不再是源内容，因此无法找到插槽位置，因此使用 load 钩子。