vue+vitepress自动生成组件文档

如何编写一套自己的组件并生成文档

背景

随着公司的组件库越来越大加上其他项目组的使用不得不将组件库抽离出来。并自动生成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

相关推荐
然我19 分钟前
不用 Redux 也能全局状态管理?看我用 useReducer+Context 搞个 Todo 应用
前端·javascript·react.js
前端小巷子24 分钟前
Web 实时通信:从短轮询到 WebSocket
前端·javascript·面试
神仙别闹28 分钟前
基于C#+SQL Server实现(Web)学生选课管理系统
前端·数据库·c#
web前端神器34 分钟前
指定阿里镜像原理
前端
枷锁—sha39 分钟前
【DVWA系列】——CSRF——Medium详细教程
android·服务器·前端·web安全·网络安全·csrf
枷锁—sha40 分钟前
跨站请求伪造漏洞(CSRF)详解
运维·服务器·前端·web安全·网络安全·csrf
群联云防护小杜1 小时前
深度隐匿源IP:高防+群联AI云防护防绕过实战
运维·服务器·前端·网络·人工智能·网络协议·tcp/ip
汉得数字平台1 小时前
【鲲苍提效】全面洞察用户体验,助力打造高性能前端应用
前端·前端监控
花海如潮淹1 小时前
前端性能追踪工具:用户体验的毫秒战争
前端·笔记·ux
_丿丨丨_6 小时前
XSS(跨站脚本攻击)
前端·网络·xss