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

本教程具有视频版本，见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: 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饿了么
---

### 设计原则

<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？

新建首页`.md`文件

创建配置文件

创建组件页

新建组件页的`.md`文件

配置顶部导航栏

配置组件页文档的侧边栏

组件展示效果实现

安装Demo插件

认识`enhanceApp.js`

引入Element组件

部署VuePress

执行部署命令

使用Web Server部署

Recommend

谈谈水印实现的几种方式

Bitcoin SV Virtual Meetup APAC: Token usefulness and challenges discussed

Use Spring IoC with servlets defined in web.xml

SegmentFault D-Day 技术沙龙随手记

Independent Reserve Gets MAS’ First in-Principle Approval for Digital Payment To...

新研究：一种脂肪“盾牌”保护免疫细胞被摧毁，同时也救下了癌细胞

为什么越来越多公司使用企业微信！

Rapyd raises $300M on $8.75B valuation

Best Bird Feeder 2021

Google Maps dark theme officially coming to iPhone this month

About Joyk

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

为什么要使用VuePress？

新建首页.md文件

创建配置文件

创建组件页

新建组件页的.md文件

配置顶部导航栏

配置组件页文档的侧边栏

组件展示效果实现

安装Demo插件

认识enhanceApp.js

引入Element组件

部署VuePress

执行部署命令

使用Web Server部署

Recommend

About Joyk

新建首页`.md`文件

新建组件页的`.md`文件

认识`enhanceApp.js`