实现vitepress自动生成vue3组件文档

合格的组件文档至少要满足以下条件

  • 要有使用示例
  • 使用示例可预览
  • 可直接查看使用示例的代码且代码可直接复制

vitepress写vue3组件文档的不足之处

未找到一款能自动生成组件文档的插件。虽说,手动编写也不是不行,但容易导致代码变更之后,组件文档与实际代码不统一的问题

一些你可能想到或找过的方案

基于以上几点, 可能只能自行实现了

期望的效果

期望在md文件中,仅编写如下代码,就能自动帮我将MyComp.vue组件的文档生成,并插入到这里

makefile 复制代码
::: VueDoc /src/test/MyComp.vue
:::

需要掌握的前置知识

实现该需求步骤

第一步:实现自定义vite插件

作用

  1. 该插件随vite启动,使用vue-docgen-api读取vue组件的props,events,slots信息,然后自行将这些数据转换为markdown内容,再将markdown内容转化为html内容,然后形成vite的虚拟文件。方便后续自定义vue组件中读取该内容,将其显示到markdown中
  2. 监听vue文件变化,当vue文件变化时,自动重启vite,从而达到重启vitepress的目的

第二步: 实现对markdown-it的扩展

通过 markdown-it-container 实现

作用

将如下标签,解析为自定义vue组件标签, 并将相对路径转为绝对路径

makefile 复制代码
::: VueDoc /src/test/Demo.vue
:::

解析后

ini 复制代码
<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)

相关推荐
qq_424409193 小时前
uniapp的app项目,某个页面长时间无操作,返回首页
前端·vue.js·uni-app
我在北京coding3 小时前
element el-table渲染二维对象数组
前端·javascript·vue.js
布兰妮甜3 小时前
Vue+ElementUI聊天室开发指南
前端·javascript·vue.js·elementui
SevgiliD3 小时前
el-button传入icon用法可能会出现的问题
前端·javascript·vue.js
我在北京coding3 小时前
Element-Plus-全局自动引入图标组件,无需每次import
前端·javascript·vue.js
鱼 空3 小时前
解决el-table右下角被挡住部分
javascript·vue.js·elementui
01传说4 小时前
vue3 配置安装 pnpm 报错 已解决
java·前端·vue.js·前端框架·npm·node.js
sunbyte6 小时前
50天50个小项目 (Vue3 + Tailwindcss V4) ✨ | DoubleVerticalSlider(双垂直滑块)
前端·javascript·css·vue.js·vue
拾光拾趣录8 小时前
虚拟DOM
前端·vue.js·dom
合作小小程序员小小店8 小时前
web网页,在线%食谱推荐系统%分析系统demo,基于vscode,uniapp,vue,java,jdk,springboot,mysql数据库
vue.js·spring boot·vscode·spring·uni-app