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

本教程具备视频版本，见 B 站《VuePress 搭建 Element 组件库文档》

社区外面有很多优良的文档工具能够供咱们前端程序员抉择，例如 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 这样，下面有组件的展现，上面是示例的代码。这一部分咱们就来看看如何实现这个成果吧

这里咱们会应用到一个 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)
  }
}

接下来咱们在方才创立的 /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>
\```(留神：须要去掉后面的‘\’！！！)
:::

如果一切顺利的话，我置信你此时应该可能看到以下的成果了：

到目前未知，组件库的根本框架就曾经搭建实现了，剩下的就是填充内容并最终部署。当初咱们来讲一下部署环节。

还记得咱们之前在 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

只需把 root 目录指向 /docs/.vuepress/dist/ 就能够部署到服务，这里咱们应用了本机的 MAMP 的 Apache 用做 Web Server。当然你也能够应用 nginx 或者任何你喜爱的服务器进行部署。

此时输出 Web Server 所配置的端口名称，就能看见曾经部署胜利了

VuePress 官网文档
demoContainer 插件

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

为什么要应用 VuePress？

装置

创立首页

新建首页 `.md` 文件

创立配置文件

启动我的项目

创立组件页

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

配置顶部导航栏

配置组件页文档的侧边栏

组件展现成果实现

装置 Demo 插件

意识`enhanceApp.js`

引入 Element 组件

部署 VuePress

执行部署命令

应用 Web Server 部署

参考资料

为什么要应用 VuePress？

装置

创立首页

新建首页 .md 文件

创立配置文件

启动我的项目

创立组件页

新建组件页的 .md 文件

配置顶部导航栏

配置组件页文档的侧边栏

组件展现成果实现

装置 Demo 插件

意识enhanceApp.js

引入 Element 组件

部署 VuePress

执行部署命令

应用 Web Server 部署

参考资料

新建首页 `.md` 文件

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

意识`enhanceApp.js`