当前位置: 首页 > Web前端 > vue.js

使用VuePress搭建Element的组件库文档官网

时间:2023-04-01 10:38:50 vue.js

本教程有视频版,看B站《VuePress搭建Element组件库文档》为什么要用VuePress?社区中有很多优秀的文档工具供我们前端程序员选择,比如Gitbook、Hexo、Docusaurus。对于个人使用,我体验过的最好的文档工具是Docusaurus。Docusaurus具有配置简单、目录结构合理、Markdown渲染配置灵活等一系列优点。但对Vue开发者不太友好的是,Docusaurus是基于React的。如果你想在里面使用Vue,渲染Vue组件,就会变得非常困难。所以如果你是Vue开发者,在编写Vue相关的组件文档时,我个人推荐使用官方的VuePress。下面的教程将使用VuePress生成一个类似Element的组件文档库,包括Vue组件展示、示例代码展示、自定义主题等常用功能。安装并创建项目vuepress-element-docmkdirvuepress-element-doc&&cdvuepress-element-doc初始化npm包管理并在package.json中添加脚本npminit-y//package.json"scripts":{"dev":"vuepressdevdocs","build":"vuepressbuilddocs"},installVuePress+Elementnpminstallvuepresselement-ui--registry=https://registry.npm.taobao.org因为我们要做的是Element组件文档页面,所以这里顺便安装Element。如果需要显示自己的组件库,可以安装或导入自己的组件库的js和css。创建主页新建主页.md文件新建docs/README.md---home:trueheroImage:https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.pngheroText:Elementfeatures:-title:ConsistencyConsistencydetails:Consistentwithreallife:符合现实生活的流程和逻辑,遵循用户习惯的语言和概念-title:Feedback反馈详情:通过界面风格和交互动态,用户可以清晰感知自己的操作-title:Efficiency效率详情:界面简洁明了,让用户快速识别而不是回忆,减轻用户的记忆负担。footer:by饿了么---###设计原则一致性

一致性

反馈

反馈

efficiency

效率

可控

Controllability

这个README.md中有三种语法:YAML:顶端以---Wrapped是YAML语法的FrontMatter,必须位于.md的最前面,可选Markdown:其中###设计原则部分就是Markdown语法,相信大家都不陌生with.html:最后是我们熟悉的HTML语法,众所周知,HTML语法可以在.md中使用。注意:docs/README.md中的图片地址是OSS上的地址,因为这样更方便你使用se。当然你也可以使用对于本地公共文件,详见Vuepress/StaticResources/PublicFiles。创建配置文件并新建docs/.vuepress/config.js,填写基本配置信息。注意这个文件是VuePress的核心文件,有丰富的配置项。module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element的组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{},head:[],plugins:[],markdown:{}}启动项目使用命令运行VuePress查看效果npmrundevbrowser访问localhost:8080,如果没有意外,相信你已经可以看到了页面上如下可以了,这个页面是我们在README.md文件中写的YAML+Markdown+HTML的整体效果。创建组件页面创建新组件页面的.md文件/docs/comps/README.md,并填写内容。这里模仿的是Element官网的安装页面。#安装##npm安装推荐使用npm安装,配合webpack打包工具使用效果更好。npmielement-ui-S##CDN目前可以通过unpkg.com/element-ui获取最新版资源,在页面导入js和css文件即可开始使用。创建/docs/comps/select.md并填写内容。创建两个文件方便我们后面设置文档侧边栏,这里是Element官网的selector组件页面。#选择选项太多时选择器,请使用下拉菜单以显示和选择内容。##基本用法适用于广泛的基础单选配置顶部导航栏在/docs/.vuepress/config.js中配置顶部导航栏的配置字段themeConfig.nav。代码如下:module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{//新代码nav:[//配置顶部导航栏{text:'Home',link:'/'},{text:'Component',link:'/comps/'}]},head:[],plugins:[],markdown:{}}在/docs/.vuepress/config.js中配置组件页面文档的侧边栏配置顶部导航栏的配置字段themeConfig.sidebar。代码如下:module.exports={theme:'',title:'VuePress+Element',description:'VuePress构建Element组件库文档教程示例代码',base:'/',port:'8080',themeConfig:{nav:[{text:'Homepage',link:'/'},{text:'Component',link:'/comps/'}],sidebar:{//配置侧边栏部分'/comps/':['/comps/','/comps/select.md']}},head:[],plugins:[],markdown:{}}在这一点上我相信你会看到这样的东西你的浏览器页面不见了,是不是有点Element文档的味道?组件显示效果的实现不过到目前为止,我们还没有介绍Element的组件部分。既然是组件库,我们自然希望能像Element一样实现组件的展示,下面是示例代码。这部分,我们来看看如何实现这个效果。安装演示插件。这里我们将使用vuepress-plugin-demo-container插件。使用以下命令安装npminstallvuepress-plugin-demo-container然后在/docs/中。在vuepress/config.js文件中配置插件module.exports={//...plugins:['demo-container'],//配置插件markdown:{}}知道enhanceApp.js的你有没有想过我们通常在项目中使用Element时,需要在app.js中引入Element,调用Vue.use(Element)才能在Vue中使用Element组件。如果我们要在VuePress中使用Element,我们需要在哪里写这段代码呢?此时我们需要知道一个新的文件enhanceApp.js,它是VuePress中仅次于config.js的第二重要的文件。当你想做一些Vue应用级别的配置时,你需要在这个文件中进行配置。让我们在这里创建这个文件:/docs/.vuepress/enhanceApp.js。从'element-ui'导入ElementUI;导入'element-ui/lib/theme-chalk/index.css';导出默认异步({Vue})=>{if(typeofprocess==='undefined'){Vue.use(ElementUI)}}导入Element组件接下来,让我们尝试在我们刚刚创建的/docs/comps/select.md中使用Element。用以下内容替换原来的内容。#选择选项太多时选择器,请使用下拉菜单以显示和选择内容。##Basicusage适用于广泛的基本radio:::demo适用于广泛的基本radio\```html(注意:需要去掉前面的'\'!!!)\```(注意:需要去掉前面的'\'!!!):::如果一切顺利,相信此时你应该可以看到如下效果:VuePress的部署目前未知,组件库的基础框架已经搭建完成,剩下的就是填写内容了,最后部署。现在让我们谈谈部署部分。执行部署命令还记得我们之前在package.json中配置了VuePress部署脚本的“build”:“vuepressbuilddocs”吗?所以我们只需要执行下面的命令用npmrunbuild查看文件,你会发现此时多了一个文件/docs/.vuepress/dist,dist目录就是我们最终的部署目录。├──文档│├──.vuepress││├──config.js││├──dist│││├──404.html│││├──资产││││├──css│││││└──0.styles.262ade0c.css││││├──字体│││││├──element-icons.535877f5.woff│││││└de.──3element39.──3element-iconsttf││││├──img│││││└──search.83621669.svg││││└──js││││├──2.ae254118││3js││.c4b624da.js││││├──4.8c48097d.js││││├──5.a4fed9a4.js│││├──6.efea7d5a.js─││e17.│4│js││││├──8.8ee7961b.js││││├──9.e8d922fc.js││││└──app.90733c82.js││││├──comps│index.html││││└──select.html│││└──index.html││└──enhanceApp.js│├──README.md│└──comps│├──README.md│└──select.md├──package-lock.json└──package.json使用WebServer部署,只需将根目录指向/docs/.vuepress/dist/即可部署到服务中,这里我们使用本地的MAMPApache作为WebServer,当然你也可以使用nginx什么的你想部署到你最喜欢的服务器。此时输入WebServer配置的端口名,可以看到已经部署成功。