Vue3与vitepress文档开发实战

382 阅读2分钟

1.项目创建及其架构

创建⽀持tsx的Vue3项⽬,使用vite创建⼀个⽀持ts的项⽬,选择vue + ts即可。 image.png 在Vite 项⽬中引⼊JSX,通过: @vitejs/plugin-vue-jsx 插件实现,并配置该插件 image.png

测试⼀下,components/Test.tsx

export default () => <div>hello TestJsx</div>

image.png

2.代码规范

通过配置 eslint + prettier 保证项⽬代码规范

2.1Eslint 配置

使⽤ eslint —-init 初始化配置⽂件 按照如图的步骤选择: image.png ⽣成了⼀个.eslintrc.cjs ⽂件

image.png

检测下eslint 是否⽣效

package.json ⽂件⾥添加 script

image.png

eslint 默认只检测.js的⽂件, 所以需要 --ext 来指定⽂件类型,详情可参考官⽹ 有的时候可能eslint没有及时的⽣效,可以重新启动下我们的编辑器

适配vue3

只需要vue的eslint的相关配置改成⼀个配置就好了

image.png

2.2添加 prettier

image.png 修改下 .eslintrc.cjs

image.png

创建 .prettierrc.js , 内容如下

image.png

image.png

2.3添加husky

npx mrm  lint-staged 生成文件 image.png

Package.json image.png

3.VitePress创建组件⽂档

yarn add -D vitepress安装VitePress 创建第⼀个⽂档: image.png 增加脚本命令: image.png

image.png

3.1配置VitePress

我们需要实现以下功能:需要⼀个左侧菜单,⽤来展示我们有哪些组件点击左侧菜单中的组件,可以展示这个组件的基本信息、Demo、API⽂档

3.1.1配置sidebar

VitePress 有⼀个配置⽂件,⾥⾯有⼀个themeConfig/sidebar配置,可以配置左侧菜单。 docs/.vitepress/config.ts

image.png image.png

3.1.2创建Button组件的⽂档

404 的原因是我们没有创建相应的⽂档,创建docs/component/button/index.md image.png 编写⼀些内容

image.png

效果: image.png 在md中增加vue组件 VitePress 的⼀⼤好处是可以直接在md中写vue组件,VitePress会将其渲染出 来,docs/components/button/index.md

image.png image.png 引⼊Button组件 docs/.vitepress/theme/index.tsx image.png 报错:React is not defined image.png

3.1.3引⼊jsx插件

 docs/vite.config.ts 中引⼊jsx插件:

image.png

3.2组件Demo代码展示

使⽤ Vitepress 编写组件示例有以下不⾜之处:

1.组件示例和示例代码本质上⼀样,却需要写两遍。

2.Vitepress ⽆法渲染 Markdown 中的 script 和 style 代码块。 image.png vitepress 有款⽀持demo展示的插件 vitepress-theme-demoblock 可以解决以上问题,写⼀遍同时显示结果和代码块,先安装: image.png 注⼊插件 ⾸先我们得知道 vitepress 关于markdown的拓展规则, vitepress 使⽤ markdown-it 作为 markdown 渲染器,具体可以 ,我们得将插件在 vitepress 的 查看 config.js 中注册,如下⾯这样: image.png docs/.vitepress/theme/index.ts 中注册 demoblock 插件所需的 demo 和 vitepress-theme demo-block 组件,以及所需样式。 image.png 接下来按要求编写⽂档,⽐如下⾯这样写 image.png 最终⽣成的效果如图所示 image.png