Vue组件库系列二:打造属于自己的 UI 库文档(老版本的方案)

前一篇文章实现了封装个人的组件库功能，有了组件库，当然还要有配套说明文档，这样使者用起来才更方便。打包完成的dist目录是最终可放到服务器中，直接访问到文档的哟。

在项目中配置打包examples

上篇文章中，执行打包命令会将项目打包至lib下，打包完成的目录结构是适合直接发布为npm包，使用时使用import等引入的。其中并没有html文件入口，所以要有说明文档，直接在浏览器中可访问，还需要重新配置打包。

细心的童鞋会发现，我们的说明文档是vue文件，而ElementUI是用markdown格式的文档，语法简介，配置方便，那他们是如何做到的呢？这篇文章将带大家逐步分析实现md文档

打包examples相关目录结构及webpack配置

一、package.json增加打包命令"build_example": "node build/build.js examples"

二、在src同级增加examples目录（删掉之前的内容），存放文档相关文件

examples目录中：

1、assets目录存放静态资源依赖，

2、components存放vue组件，

3、docs目录存放.md文件，说明文档，

4、main.js会作为打包的入口，在这里引入项目的组件、第三方依赖：element-ui、路由配置等，

5、route.js路由配置，

6、index.html作为打包的html模版，

7、App.vue

三、webpack相关配置

在build目录中增加webpack.prod.examples.conf.js文件，配置打包example。这个文件是vue-cli生成项目中的webpack.prod.conf.js稍作修改，改动部分：

1、增加output出口配置，由于之前在config中将这个值设置成了../lib，这里把值设置为../dist，将examples打包后输出到dist

2、设置打包入口为examples下的main.js

3、设置html模版为./examples/index.html

另外在build/build.js中，需要判断example参数，更改一下output出口路径，如图：

相关依赖安装

npm i highlight -D //安装语法高亮
npm i markdown-it markdown-it-anchor markdown-it-container -D // 安markdown 相关依赖
npm i vue-markdown-loader -D //安装vue-markdown-loader，解析.md文件为.vue文件

webpack相关配置

安装了vue-markdown-loader解析.md文件，在webpack.base.conf.js文件中，需要进行相关的loader配置，这里的配置相关，都是copy的element-ui中的代码。改动部分如下：

一、首先增加strip-tags文件到/build目录中，strip-tags内容如下：

二、webpack.base.conf.js的改动

1、增加工具函数

2、增加.md相关loader配置,将.md文件解析为.vue文件，同时，解析处理::: demo :::代码块等，解析处理::: demo :::代码块为demo-block vue组件，并传入对应参数.

文档编写部分

配置相关的就告一段落了，接下来进入examples中的文档编写部分

一、main.js入口文件编写

在入口文件中，引入相关依赖，项目样式入口、路由、组件以及element-ui

二、设置路由配置route.js

路由配置时，将路由路径对应的组件设置为引入的.md文件

三、App.vue、以及相关布局组件

1、App.vue

2、header.vue

3、menu.vue（这里我们借用一下element-ui的menu组件）

四、重要组件demoBlock.vue

demoBlock组件是解析.md中的::: demo ::: 代码块需要用到的组件，这里的demoBlock.vue文件是copy的element-ui的代码后稍作修改（这个部分和loader中配置的相对应）

主要的代码放在这里了，样式文件大家可以去element-ui里面看

五、docs中的.md文档文件

.md文件编写时有几个需要注意的地方：

具有交互功能的说明文档，需要有<script></script>标签，在标签元素中定义需要导出的vue实例（这一部分将是下一个版本着重更新的地方）。

在:::demo ::: 代码块中定义的模版<template></template>会作为导出的vue实例的模版，但是在代码块中的<script></script>中的内容仅作为展示。

.md文件粘贴进来会展示有误，这里只进行了截图，有需要的伙伴可以进入github查看

六、样式调整

样式相关的调整代码这里就不单独列出来说明了，需要的伙伴可以进入github查看

开发

开发中的调试

设置webpack.dev.conf.js文件的入口为./examples/main.js，这样即可以边开发组件边调试，同时也可以调试到说明文档。

entry: {
 app: './examples/main.js'
 },

结束语

本文带着大家过了一遍element-ui组件库文档编写的过程，大家可以参照例子集成到自己的组件库中。同时在本文的内容中介绍了这种方式的”不足之处“和下一版本的改进方向，我们会沿着这个方向继续打造我们的组件库文档