Vitepress搭建组件库文档(下)—— 组件 Demo
上文 《Vitepress搭建组件库文档(上)—— 基本配置》已经讨论了 vitepress 搭建组件库文档的基本配置,包括站点 Logo、名称、首页 home 布局、顶部导航、左侧导航等。本文进入最重要的部分 —— 如何像 Element Plus 那样一遍代码就可以展示组件的效果和源代码。
1 组件 Demo 的实现效果
vitepress 对 MarkDown 支持比较好,同时对 vue3 也支持较好。常见的在 MD 文档中展示 Demo 有两种方式:
- 在一个区块内展示,添加插件用来解析 demo 区块,如:
组件基本使用:
:::demo 描述信息
<template>
<el-button type="primary">测试按钮</el-button>
</template>
:::
- 封装一个组件,将 Demo 代码的语言、路径传递给该组件,然后在 MD 文档中使用该组件,如:
组件基本使用:
<code-preview path="../demos/xx/xxx.vue"
language="vue">
如果某个组件文档中 demo 较少,可以使用第一种方式,直接在 MD 文档中编写组件 demo;但如果 demo 较多或 demo 实现较复杂,可以使用第二种方式。所以最好两种方式都支持。
在 vitepress 1.0 之前(如 0.22.0),vitepress-theme-demoblock 是个非常好的选择,支持区块内的方式展示 Demo 和示例代码,但从 npmjs 上面可以看到该插件有一年多没更新了,在 vitepress 1.0 中会报错。不停搜索,总算找到一个可以很好支持 vitepress 1.0 的插件 —— vitepress-demo-preview,这里非常感谢 vitepress-demo-preview 的作者 flingyp 大神!
2 集成 @vitepress-demo-preview
2.1 安装依赖
pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin
2.2 config.ts
修改 docs/.vitepress/config.ts,添加 markdown 配置:
import { componentPreview, containerPreview } from '@vitepress-demo-preview/plugin'
...
export default defineConfig({
...
markdown: {
theme: {
light: 'vitesse-light',
dark: 'vitesse-dark'
},
lineNumbers: true,
config(md) {
md.use(componentPreview)
md.use(containerPreview)
}
}
})
2.3 组件引入
在 .vitepress 下新建目录 theme,并在 theme 目录中创建 index.ts
import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'
export default {
...theme,
enhanceApp({app}) {
app.component('demo-preview', AntDesignContainer)
}
}
这样便完成了 @vitepress-demo-preview 的配置,接下来就可以在组件文档中编写demo了。
3 编写组件 demo
这里由于是演示,就不编写测试组件了,简单的使用 Element-Plus 来模拟组件库,在文档使用 Button 编写 Demo。
3.1 引入组件库
安装组件库依赖:
pnpm install element-plus
在 .vitepress/theme/index.ts 中安装组件库:
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'
export default {
...theme,
enhanceApp({app}) {
app.use(ElementPlus)
app.component('demo-preview', AntDesignContainer)
}
}
3.2 编写组件 Demo
在 docs 目录下创建 demo 目录,该目录存放文档中编写的demo,如定义一个 button-demo-1.vue 文件:
<template>
<el-button type="primary">测试按钮</el-button>
</template>
在 docs/compnents/basic-component1.md 中使用该 Demo:
# Basic Component 1
<preview path="../demos/button-demo-1.vue" title="基本使用" description="xxxxx"></preview>
预览该页面:
使用这个插件,只能在文档外部定义组件 Demo,不支持在 MD 文档中编写 Demo。
4 打包组件库
组件库打包完成后,需要打包发布。
打包:
pnpm run build
预览组件库:
pnpm run serve
vitepress 编写组件库文档就先介绍到这里。后面将分享 pnpm + monorepo + vite + vue3 + tsx + vitepress 搭建企业级组件库,内容大纲如下:
- pnpm 搭建 monorepo 风格架构;
- 组件库开发环境搭建和构建发布;
- 组件库演示 example 开发环境搭建和构建发布;
- 组件库文档开发环境搭建和构建发布;
- 命令行工具开发。
感谢你阅读本文,如果本文给了你一点点帮助或者启发,还请三连支持一下,点赞、关注、收藏,作者会持续与大家分享更多干货
Vitepress搭建组件库文档(下)—— 组件 Demo的更多相关文章
- 使用VitePress搭建及部署vue组件库文档
每个组件库都有它们自己的文档.所以当我们开发完成我们自己的组件库必须也需要一个组件库文档.如果你还不了解如何搭建自己的组件库可以看这里->从零搭建Vue3组件库.看完这篇文章你就会发现原来搭建和 ...
- Vitepress搭建组件库文档(上)—— 基本配置
在 vite 出现以前,vuepress 是搭建组件库文档不错的工具,支持以 Markdown 方式编写文档.伴随着 vite 的发展,vitepress 已经到了 1.0.0-alpha.22 版本 ...
- Web 前端 UI 组件库文档自动化方案 All In One
Web 前端 UI 组件库文档自动化方案 All In One 需求 自动化 动态 好用 markdown element-ui 中示例和说明按照一定规则写在md文件中,调用md-loader将md文 ...
- 使用dumi生成react组件库文档并发布到github pages
周末两天玩了下号称西湖区东半球最牛逼的react文档站点生成工具dumi,顺带结合github pages生成了react-uni-comps文档站, 一套弄下来,感觉真香,现在还只是浅尝,高级的特性 ...
- vuepress搭建UI组件库文档踩坑篇
为了实现组件效果预览及代码展示可折叠功能,使用了插件vuepress-plugin-demo-container 相关配置可参考官网说明文档 第一步 安装插件 npm i - D vuepress-p ...
- 一款开源免费的.NET文档操作组件DocX(.NET组件介绍之一)
在目前的软件项目中,都会较多的使用到对文档的操作,用于记录和统计相关业务信息.由于系统自身提供了对文档的相关操作,所以在一定程度上极大的简化了软件使用者的工作量. 在.NET项目中如果用户提出了相关文 ...
- flexpaper 开源轻量级的在浏览器上显示各种文档的组件
FlexPaper是一个开源轻量级的在浏览器上显示各种文档的组件,被设计用来与PDF2SWF一起使用, 使在Flex中显示PDF成为可能,而这个过程并无需PDF软件环境的支持.它可以被当做Flex的库 ...
- 推荐一套.NET文档处理组件Spire.Office
原文:推荐一套.NET文档处理组件Spire.Office 以前的项目中用到一点Word简单处理的功能(文字替换和转PDF格式),当时使用的是一套COM组件,必须在服务器上安装office环境.最近考 ...
- DCloud-MUI:文档 UI组件
ylbtech-DCloud-MUI:文档 UI组件 1.返回顶部 1.accordion(折叠面板) 折叠面板从二级列表中演化而来,dom结构和二级列表类似,如下: <ul class=&qu ...
随机推荐
- Windows 11上Dev C++ 5.11 提示 Failed to execute xxx Error 0的一种解决方法
问题现象 在Windows 11上用Dev C++ 5.11编译运行程序,出现如下错误不能运行,且自己的程序没有问题. 可能的原因 Dev C++没有以管理员身份运行? 生成的程序所在的目录受到了访问 ...
- ArcGIS QGIS学习一:打开shp、geojson地图变形变扁问题(附最新坐标边界下载全国省市区县乡镇)
目录 打开的地图变扁了 修改投影坐标系 等角圆锥投影 Web墨卡托投影 一些要注意的地方 打开的地图变扁了 记得初学GIS软件时,用ArcGIS或QGIS打开省级地图的时候(shp或geojson等格 ...
- React报错之Unexpected default export of anonymous function
正文从这开始~ 总览 当我们尝试使用默认导出来导出一个匿名函数时,会导致"Unexpected default export of anonymous function"警告.为了 ...
- 【HTML】学习路径4-align对齐-标签属性
每个标签都可以设置各种属性,比如可以给一个段落标签添加一个name的属性: <p name="段落标签1"> 这一节我们学习一个属性:align对齐标签 第一章:ali ...
- vivo前端智能化实践:机器学习在自动网页布局中的应用
作者:vivo 互联网前端团队- Su Ning 在设计稿转网页中运用基于self-attention机制设计的机器学习模型进行设计稿的布局,能够结合dom节点的上下文得出合理的方案. 一.背景 切图 ...
- Qt 场景创建
1 创建 Q t Widget Application 2 创建窗口 3 创建后的目录 创建完成后运行一下 4 导入资源 将res文件拷贝到 项目工程目录下 添加资源 选择一模版.Qt-Reso ...
- KingbaseES R6 集群主库网卡down测试案例
数据库版本: test=# select version(); version ------------------------------------------------------------ ...
- phpoffice文档笔记
目录 phpword html转word phpexcel 从数据库导出 phpword html转word <?php namespace app\index\controller; use ...
- Python Web开发主流框架
Web 开发是Python 语言应用领域的重要部分,也是工作岗位最多的领域.如果你对基于Python的Web 开发有兴趣,正打算使用Python 做Web 开发,或者已经是一个Web 开发者有工作需要 ...
- .NET 部署Https(SSL)通过代码方式
在上一个文章中,传送门,给大家介绍了怎么在配置文件中使用 Kestrel 部署 Https,正好今天有小伙伴稳问到:可以通过代码的方式实现 Kestrel 的 Https 的部署吗?答案是肯定的,我们 ...