手把手使用VuePress搭建Element的组件库文档官网
本教程具有视频版本,见B站 《VuePress搭建Element组件库文档》为什么要使用VuePress? 社区里面有很多优秀的文档工具可以供我们前端程序员选择,例如Gitbook、Hexo、Docusaurus。就个人使用而言,体验最好的文档工具是Docusaurus。
![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/c5fdd9deb649478a973fda004ffe8680.jpg)
文章图片
Docusaurus具有配置简单,目录结构合理、Markdown渲染配置灵活等一系列的优点。但对于Vue的开发者不太友好的是,Docusaurus是基于React的,如果你想在其中使用Vue的写法和渲染Vue组件会变得十分困难。所以如果你是Vue的开发者,在编写Vue相关组件文档的时候,个人还是推荐使用官方的VuePress。
下面的教程会使用VuePress生成类似Element的组件文档库,包括Vue组件展示、示例代码展示、自定义主题等常用功能。
安装
- 创建项目
vuepress-element-doc
mkdir vuepress-element-doc && cd vuepress-element-doc
- 初始化npm包管理并在
package.json
中新增脚本
npm init -y
// package.json"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},
- 安装 VuePress + Element
npm install vuepress element-ui --registry=https://registry.npm.taobao.org
因为我们要做的是Element的组件文档页,所有这里顺便安装一下Element。你如果需要展示你自己的组件库,那么安装或引人自己的组件库的js和css即可。
创建首页 新建首页
.md
文件新建
docs/README.md
---
home: true
heroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.png
heroText: Element
features:
- title: 一致性 Consistency
details: 与现实生活一致:与现实生活的流程、逻辑保持一致,遵循用户习惯的语言和概念
- title: 反馈 Feedback
details: 通过界面样式和交互动效让用户可以清晰的感知自己的操作
- title: 效率 Efficiency
details: 界面简单直白,让用户快速识别而非回忆,减少用户记忆负担。
footer: by饿了么
---### 设计原则
文章图片
一致性
Consistency
文章图片
反馈
Feedback
文章图片
效率
Efficiency
文章图片
可控
Controllability
这个
README.md
中一共有三种语法:- YAML: 顶部以
---
包裹起来的是YAML语法的Front Matter,这个语法必须位于.md
的顶部,是可选的。 - Markdown: 其中
### 设计原则
部分是Markdown语法,相信大家都很熟悉。 - HTML: 最后是我们熟悉的HTML语法,总所周知,在
.md
中是可以使用HTML语法的。
备注:docs/README.md中的图片地址是放到OSS上的地址,因为这样更方便使用。当然你也可以使用本地的公共文件,具体见 Vuepress/静态资源/公共文件。创建配置文件
新建
docs/.vuepress/config.js
,填入基本的配置信息。注意,这个文件是VuePress最核心的一个文件,有着丰富的配置项。module.exports = {
theme: '',
title: 'VuePress + Element',
description: 'VuePress搭建Element的组件库文档教程示例代码',
base: '/',
port: '8080',
themeConfig: {},
head: [],
plugins: [],
markdown: {}
}
启动项目
使用命令运行VuePress,查看效果
npm run dev
浏览器访问
localhost:8080
,如果没有意外,我相信你已经能够在页面上看到如下的效果了,这个页面就是我们在README.md
这个文件中所编写的YAML + Markdown + HTML的整体效果。![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/58959cb33d4d4ee496162e40e3c4e113.jpg)
文章图片
创建组件页 新建组件页的
.md
文件创建
/docs/comps/README.md
, 填入内容。这里模仿的是Element官网的安装页面。# 安装## npm安装推荐使用 npm 的方式安装,它能更好地和 webpack 打包工具配合使用。npm i element-ui -S## CDN
目前可以通过 unpkg.com/element-ui 获取到最新版本的资源,在页面上引入 js 和 css 文件即可开始使用。
创建
/docs/comps/select.md
,填入内容。创建两个文件是方便我们之后设置文档侧边栏, 这里模仿的是Element官网的选择器组件页面。# Select 选择器当选项过多时,使用下拉菜单展示并选择内容。## 基本用法适用广泛的基础单选
配置顶部导航栏
在
/docs/.vuepress/config.js
中配置顶部导航栏的配置字段 themeConfig.nav
。代码如下:module.exports = {
theme: '',
title: 'VuePress + Element',
description: 'VuePress搭建Element的组件库文档教程示例代码',
base: '/',
port: '8080',
themeConfig: { // 新增代码
nav: [ // 配置顶部导航栏
{
text: '首页',
link: '/'
},
{
text: '组件',
link: '/comps/'
}
]
},
repo: 'http://gitlab.17zuoye.net/tanghui.li/Apollo.js',
head: [],
plugins: [],
markdown: {}
}
配置组件页文档的侧边栏
在
/docs/.vuepress/config.js
中配置顶部导航栏的配置字段 themeConfig.sidebar
。代码如下:module.exports = {
theme: '',
title: 'VuePress + Element',
description: 'VuePress搭建Element的组件库文档教程示例代码',
base: '/',
port: '8080',
themeConfig: {
nav: [
{
text: '首页',
link: '/'
},
{
text: '组件',
link: '/comps/'
}
],
sidebar: { // 配置侧边栏部分
'/comps/': ['/comps/', '/comps/select.md']
}
},
head: [],
plugins: [],
markdown: {}
}
此时我相信你就能够在浏览器上看到这样的页面了,是不是有一点Element文档的味道了。
![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/6ce82e550971415dbf2818ace3a30aaa.jpg)
文章图片
组件展示效果实现 可是到目前为止,我们还没有引入Element的组件部分,既然是一个组件库,我们自然希望实现像Element这样,上面有组件的展示,下面是示例的代码。这一部分我们就来看看如何实现这个效果吧
![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/c94eed0f86684f0ba4f042a304cea334.jpg)
文章图片
安装Demo插件
这里我们会使用到一个
vuepress-plugin-demo-container
这个插件,使用以下命令安装npm install vuepress-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
。import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
export default async ({
Vue
}) => {
if (typeof process === 'undefined') {
Vue.use(ElementUI)
}
}
引入Element组件
接下来我们在刚才创建的
/docs/comps/select.md
中使用Element试试看吧。使用下面的内容替换原有的内容吧。# Select 选择器当选项过多时,使用下拉菜单展示并选择内容。## 基本用法适用广泛的基础单选::: demo 适用广泛的基础单选
\```html(注意:需要去掉前面的‘\’!!!)
\```(注意:需要去掉前面的‘\’!!!)
:::
如果一切顺利的话,我相信你此时应该能够看到以下的效果了:
![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/5532598eaa80432c8f42545a3089fc4c.jpg)
文章图片
部署VuePress 到目前未知,组件库的基本框架就已经搭建完成了,剩下的就是填充内容并最终部署。现在我们来讲一下部署环节。
执行部署命令
还记得我们之前在
package.json
中配置VuePress部署脚本的"build": "vuepress build docs"
吗?所以我们只需要执行以下命令即可npm run build
查看文件,你会发现此时
/docs/.vuepress/dist
这个文件多了出来,dist
目录就是我们的最终部署目录。├── docs
│├── .vuepress
││├── config.js
││├── dist
│││├── 404.html
│││├── assets
││││├── css
│││││└── 0.styles.262ade0c.css
││││├── fonts
│││││├── element-icons.535877f5.woff
│││││└── element-icons.732389de.ttf
││││├── img
│││││└── search.83621669.svg
││││└── js
││││├── 2.ae254118.js
││││├── 3.c4b624da.js
││││├── 4.8c48097d.js
││││├── 5.a4fed9a4.js
││││├── 6.efea7d5a.js
││││├── 7.fc05164e.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
使用Web Server部署
只需把root目录指向
/docs/.vuepress/dist/
就可以部署到服务,这里我们使用了本机的MAMP的Apache用做Web Server。当然你也可以使用nginx或者任何你喜欢的服务器进行部署。![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/68884dadf7154daa887a3a900757df8e.jpg)
文章图片
此时输入Web Server所配置的端口名称,就能看见已经部署成功了
【手把手使用VuePress搭建Element的组件库文档官网】
![手把手使用VuePress搭建Element的组件库文档官网](https://img.it610.com/image/info9/cb61e078d1de41b799559403892a2600.jpg)
文章图片
参考资料
- VuePress官方文档
- demoContainer插件
推荐阅读
- 由浅入深理解AOP
- 【译】20个更有效地使用谷歌搜索的技巧
- mybatisplus如何在xml的连表查询中使用queryWrapper
- MybatisPlus|MybatisPlus LambdaQueryWrapper使用int默认值的坑及解决
- MybatisPlus使用queryWrapper如何实现复杂查询
- iOS中的Block
- Linux下面如何查看tomcat已经使用多少线程
- 使用composer自动加载类文件
- android|android studio中ndk的使用
- 使用协程爬取网页,计算网页数据大小