为 vitepress 添加更专业的 Demo 演示能力

本文内容已经全部整理到 Github，你也可以查看示例站点。

背景

vitepress 凭借着 vite 的秒级启动速度、markdown-it 的强大扩展能力、天然支持 vue3 在文档圈迅速流行开来，使用 vitepress 做 vue3 组件库文档也已经非常流行。笔者也有幸实践过一次，在这里记录一下。

首先 vitepress 的 markdown 扩展能力无疑是极香的，我觉得及其舒适的有以下几点：

笔者使用 vitepress 搭建业务组件库的文档，依赖 element-plus，根据 vitepress 文档，写了一个简单的 DemoContainer 组件用于包裹 Demo。

vitepress 缺点

随着时间的推移和组件数量的累积，现有的开发方式逐渐暴露出来一些问题：

无法演示全屏组件(height:100vh)
无法演示路由组件（耦合 vue-router，如 menu-item）
vitepress 有一些全局样式挺烦的，经常干扰到 Demo，比如：

table {
  display: block;
  border-collapse: collapse;
  margin: 1rem 0;
  overflow-x: auto;
}

引用 demo 太繁琐，而且易出错（引用一个 Demo 要 15 行代码）

<script setup>
  // 这个 demo1 重复了多次，复制修改的时候容易漏掉
  import Demo1 from './demo/demo1.tsx'
</script>

<DemoContainer title="基本使用">
<ClientOnly>
<Demo1 />
</ClientOnly>
  <details>
    <summary>查看代码</summary>

<!-- 这个源码引用方式是 vitepress 提供的 -->

<<< packages/query-table/demo/demo1.tsx

  </details>
</DemoContainer>

前两点很容易想到用 iframe 是完美的解决方案，而且还能顺手解决第三点。

总结一下缺点有两个：

Demo 引用繁琐
缺少 iframe 模式

前置介绍

涉及到的框架之间的关系

vitepress 本质上是一个 vite 插件，使用它开发的文档网站效果相当于 vue3 + vite 的 ssr 项目，它在内部帮你把所有逻辑都封装好了，你只需要写 markdown 就行。

对 markdown 的扩展能力是基于 markdown-it 写了很多 markdown-it 插件。源码里所写的 markdown 文档最终都会转成 vue 组件，原理如下：

vitepress 运行 vue 组件原理

把 markdown 编译成 html 字符串，把 html 字符串拼凑成一个 vue 字符串，交给 vue-loader，处理成一个 vue 组件挂载到页面上。

调研

dumi 效果完美，可以说是标杆了。但是不支持 vue
storybook 并不是想要的 iframe 模式，也不行。
vitepress-for-component 是 fork 了 vitepress（因为 vitepress 目前未支持插件），提供了 demo 演示能力，但是没有 iframe 模式。
element-plus 也是用 vitepress , 但是也没有 iframe 模式。而且它的引用方式不清晰、不灵活。
自研，舍不得 vitepress 的 markdown 扩展能力。不到走投无路不要自研。

最终决定尝试通过修改配置和自定义插件解决。

研发

demo 引入简化

参考了 element-plus 和 vitepress-for-component ，定制一个 markdown-it 插件修改 html 编译结果。

引入方式设计

element-plus 的引入方式不够清晰，也不够灵活。采用相对路径更清晰更灵活：

<demo src="./demo-example.vue" title="Demo演示" desc="这是一段描述" />

当然 container 的方式也顺便兼容下，里面的内容可以写写 markdown：

::: demo src="./demo-example.vue" title="Demo 演示"

这是一段描述，可以用 `Markdown` 来写

:::

插件思路

遇到特定标记（如：<demo src=xxx ... />)，根据标记拼接字符串，将来会被插入到 vue template 里相应位置，通常情况下拼接 <DemoContainer ... ><Demo/></DemoContainer>，如果标记了以 iframe 模式运行 demo，则拼接一个<iframe src=xxx ... />

此过程还会包括如下步骤，感兴趣可以看源码：

插入 import statement 语句
记录 demoId 和入口的对应关系

这一步把引入 Demo 的过程从原来的 15 行代码之间简化到 1 行。

iframe 模式

运行时动态创建 iframe

试过在 DemoContainer 里 document.createElement(‘iframe’)，但是没有成功：

获取到 slot 内容的时候，组件代码已经运行了，此时放入沙箱已经晚了。
获取到 demo 源代码交给 vue-compiler 编译这个编译工作在运行时做不现实。

微前端

这明显更复杂了，而且和动态 iframe 具有相同的问题。

在 vite 配置里直接加入口

第一个念头是 vite.config 里添加入口，因为 vite 就是支持多个 html 的。

实际操作之后发现根本行不通：vitepress 接管路由了，访问任何路径都会经过 vitepress router 处理。即使设置 base，也会收到 vitepress 的提醒。

查看源码得知，devServer 拦截了所有 html 请求，根据请求路径动态生成 html：

查看代码 vitepress/src/node/plugin.ts

const vitePressPlugin: Plugin = {
  name: "vitepress",
  // ...
  configureServer(server) {
    if (configPath) {
      server.watcher.add(configPath);
    }

    // serve our index.html after vite history fallback
    return () => {
      server.middlewares.use((req, res, next) => {
        if (req.url!.endsWith(".html")) {
          res.statusCode = 200;
          res.end(`
<!DOCTYPE html>
<html>
  <head>
    <title></title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <meta name="description" content="">
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/@fs/${APP_PATH}/index.js"></script>
  </body>
</html>`);
          return;
        }
        next();
      });
    };
  },
};

定制 devServer 中间件

上面 vitepress 的操作给了我灵感，我也写个 devServer 中间件，根据请求路径动态生成 html。试了一下，还真成功了，流程如下：

上面提到定制的 markdown-it 修改 html 输出为 <iframe src=xxx />
浏览器会向 devServer 请求 iframe 地址
devServer 中间件拿到这个请求，如果命中约定格式，比如 /^\/~demos\/(?<demoId>\w+)\.html$，则拼接一个可以运行此 demo 的 html 字符串给浏览器。
1. 找到 demoId 对应的入口文件 demoEntry
2. 写一些运行时 script 作为入口
  1. 通过入口地址从 vite 请求编译结果：const module = await import('@fs/${demoEntry}')
  2. 约定 module.default 导出自动挂载的组件。否则视为 demoEntry 自行挂载

构建模式

由于构建模式没有 devServer，所以上述 devServer 也不会生效。

vitepress 和处理请求一样一刀切，没有留余地，无法通过 vite 添加入口。

所以只能在 vitepress build 之后再跑一遍 vite build -c=xxx

总结

由于这套刚刚出炉，所以有很多的优化点，发出来权当抛砖引玉了。

因为 vitepress 暂时没有插件机制，所以这套方案也没什么抽象的点子，暂时作为一个样板仓库，仓库地址，使用方法：

yarn create vitepress-demo

如果你有好的点子或者优化的地方，我们评论区见。