本教程具备视频版本，见B站《VuePress搭建Element组件库文档》
为什么要应用VuePress？
社区外面有很多优良的文档工具能够供咱们前端程序员抉择，例如Gitbook、Hexo、Docusaurus。就集体应用而言，体验最好的文档工具是Docusaurus。
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: trueheroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.pngheroText: Elementfeatures:- title: 一致性 Consistency details: 与现实生活统一：与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念- title: 反馈 Feedback details: 通过界面款式和交互动效让用户能够清晰的感知本人的操作- title: 效率 Efficiency details: 界面简略直白，让用户疾速辨认而非回顾，缩小用户记忆负担。footer: by饿了么---### 设计准则<div style="display:flex;justify-content: space-between;padding-bottom:40px"> <div style="display: flex;flex-direction: column;align-items: center;"> <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/consistency.png" alt="一致性"> <p style="margin:5px">一致性</p> <p style="margin:0px;font-size: 12px;color:#666">Consistency</p> </div> <div style="display: flex;flex-direction: column;align-items: center;"> <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/feedback.png" alt="反馈"> <p style="margin:5px">反馈</p> <p style="margin:0px;font-size: 12px;color:#666"> Feedback</p> </div> <div style="display: flex;flex-direction: column;align-items: center;"> <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/efficiency.png" alt="效率"> <p style="margin:5px">效率</p> <p style="margin:0px;font-size: 12px;color:#666">Efficiency</p> </div> <div style="display: flex;flex-direction: column;align-items: center;"> <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/controllability%20%20.png" alt="可控"> <p style="margin:5px">可控</p> <p style="margin:0px;font-size: 12px;color:#666">Controllability</p> </div></div>这个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的整体成果。
创立组件页
新建组件页的.md文件
创立 /docs/comps/README.md , 填入内容。这里模拟的是Element官网的装置页面。
# 装置## npm装置举荐应用 npm 的形式装置，它能更好地和 webpack 打包工具配合应用。npm i element-ui -S## CDN目前能够通过 unpkg.com/element-ui 获取到最新版本的资源，在页面上引入 js 和 css 文件即可开始应用。<!-- 引入款式 --><link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css"><!-- 引入组件库 --><script src="https://unpkg.com/element-ui/lib/index.js"></script>创立 /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文档的滋味了。
组件展现成果实现
可是到目前为止，咱们还没有引入Element的组件局部，既然是一个组件库，咱们天然心愿实现像Element这样，下面有组件的展现，上面是示例的代码。这一部分咱们就来看看如何实现这个成果吧
装置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(留神：须要去掉后面的‘\’！！！)<template> <el-select v-model="value" placeholder="请抉择"> <el-option v-for="item in options" :key="item.value" :label="item.label" :value="item.value"> </el-option> </el-select></template><script> export default { data() { return { options: [{ value: '选项1', label: '黄金糕' }, { value: '选项2', label: '双皮奶' }], value: '' } } }</script>\```(留神：须要去掉后面的‘\’！！！):::如果一切顺利的话，我置信你此时应该可能看到以下的成果了：
部署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或者任何你喜爱的服务器进行部署。
此时输出Web Server所配置的端口名称，就能看见曾经部署胜利了
参考资料
- VuePress官网文档
- demoContainer插件