如何编写一套自己的组件并生成文档
背景
随着公司的组件库越来越大加上其他项目组的使用不得不将组件库抽离出来。并自动生成md文档,并使用vitepress直观的展示文档。
效果图
技术栈
- vitepress
- vue-docgen-cli
使用vue-docgen-cli将组件注释生成md文件,并用vitepress展示
安装
js
yarn add -D vue-docgen-cli
生成md文件
首先,需要对我们的组件进行注释的编写例如:
vue
<template>
<button>按钮{{ text }}
<!-- @slot Use this slot to have a header -->
<slot name="header" />
</button>
</template>
<script>
/**
* 组件使用的命名
* @displayName Best Button
* @author Yoge
*/
export default {
name: 'Button',
props: {
/**
* 按钮文本
*/
text: {
type: String,
required: true,
},
/**
* 按钮大小
* @values small, medium, large
*/
size:{
type: String,
default: 'small',
}
},
methods: {
/**
* Insert text at cursor position.
*
* @param {string} text
* @public
*/
add(text) {
console.log('add');
/**
* 成功事件.
*
* @event success
* @type {object}
*/
this.$emit('success', {})
},
},
};
</script>
配置docgen config文件
创建docgen.config.js文件
js
/** @type import("vue-docgen-cli").DocgenCLIConfig */
module.exports = {
componentsRoot: 'src/components',
components: '**/[A-Z]*.(vue|ts)',
outDir: './docs/components',
}
- componentsRoot: 生成md的根目录
- components: 对应的组件
- outDir: md文件的输出目录
最后执行命令生成文件。
npx vue-docgen
结合vitepress展示文档
安装
js
add -D vitepress
根据提示创建vitepress
csharp
npx vitepress init
bash
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└
修改.vitepress/config文件
js
const path = require('path')
const glob = require('globby')
const cwd = path.join(__dirname, '..')
const { parse } = require('vue-docgen-api')
module.exports = async () => {
const sidebar = glob.sync('components/**/*.md', { cwd }).map(f => f)
return {
base: '/',
head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }]],
title: 'VuePress DocGen Live',
themeConfig: {
// 左侧栏
sidebar:sidebar.map(item=>{
return {
text:item.split('/')[1],
link: '/'+item
}
}),
search: {
// 开启搜索
provider: 'local'
}
},
}
}
执行指令就能得到我们的组件代码文档咯!!!
js
npx vitepress dev docs
写在最后
这只是最简单的一些用法,有兴趣的小伙伴可以自行阅读官网文档vitepress. Vue Styleguidist