实现vitepress自动生成vue3组件文档
站长
· 阅读数 5
合格的组件文档至少要满足以下条件
- 要有使用示例
- 使用示例可预览
- 可直接查看使用示例的代码且代码可直接复制
vitepress写vue3组件文档的不足之处
未找到一款能自动生成组件文档的插件。虽说，手动编写也不是不行，但容易导致代码变更之后，组件文档与实际代码不统一的问题
一些你可能想到或找过的方案
- Vue Styleguidist (vue-styleguidist.github.io), 遗憾的是他不支持vue3，仅vue2可以使用
- Storybook: Frontend workshop for UI development, 很强，基本可用，但实际使用的时候，有各种问题，因此我觉得不太适合
- vite-plugin-vuedoc，很久没维护了
基于以上几点, 可能只能自行实现了
期望的效果
期望在md文件中，仅编写如下代码，就能自动帮我将MyComp.vue组件的文档生成，并插入到这里
::: VueDoc /src/test/MyComp.vue
:::
需要掌握的前置知识
- 自定义vite插件实现虚拟模块功能: Vite 插件编写之虚拟模块 - 大前端探索 - SegmentFault 思否
- 在vitepress中扩展
markdown-it: Markdown Extensions | VitePress - 在vitepress注入全局vue组件: Using a Custom Theme | VitePress
- 会使用
vue-docgen-api读取vue组件的props,events,slots信息: 让通义千问给你几个示例 - 会nodejs，处理路径相关的事项
实现该需求步骤
第一步：实现自定义vite插件
作用
- 该插件随vite启动，使用
vue-docgen-api读取vue组件的props,events,slots信息，然后自行将这些数据转换为markdown内容，再将markdown内容转化为html内容，然后形成vite的虚拟文件。方便后续自定义vue组件中读取该内容，将其显示到markdown中 - 监听vue文件变化，当vue文件变化时，自动重启vite，从而达到重启vitepress的目的
第二步: 实现对markdown-it的扩展
通过 markdown-it-container 实现
作用
将如下标签，解析为自定义vue组件标签, 并将相对路径转为绝对路径
::: VueDoc /src/test/Demo.vue
:::
解析后
<MyVueDoc absoluteFilePath="E:/project/test/src/test/Demo.vue"></MyVueDoc>
第三步: 实现这个MyVueDoc组件，并在vitepress中进行全局注册
作用
读取vite的虚拟文件(该虚拟文件有组件的绝对路径以及组件的html文档)，然后，通过传入的绝对路径，从虚拟文件中找到对应的组件html文档，然后，将其渲染到界面上
第四步: 慢慢打磨，使其更符合你的需求
你可能的疑惑
为什么要这么多自定义组件配合? 不能在一个地方实现吗？
答：不能在一个地方实现。
原因：
- 因为需要通过node读取vue源文件，而vue组件中是无法使用node相关能力的
markdown-it的扩展可以使用node相关能力，但不接收返回Promise结果，而vue-docgen-api解析结果是一个Promise
成品的大概效果
参考资料
为 vitepress 添加更专业的 Demo 演示能力 - 知乎 (zhihu.com)
vitepress-demo-preview: vitepress中显示vue的demo和源代码的插件 (gitee.com)