背景

我们现在有自己的组件库了，但是单纯靠我们的README文件告诉使用者，还是不太高大上哈，而且也不能直接使用demo，所以我找到vuepress

什么是vuepress

vuepress是基于markdown的一款文档编写工具，官网是这么说的：

VuePress 由两部分组成：第一部分是一个极简静态网站生成器 (opens new window)，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

vuepress和Docsify进行比较的优缺点

优点：

  • 本身就类似于一个vue项目，可以自行配置webpack打包，就配置来说，还是比较容易懂的
  • 主题和和插件比较容易扩展
  • 可以直接展示vue组件的demo
  • 友好的seo
  • 主题简洁

缺点：

  • 不如docsify容易上手，配置比较多些（因为vuepress实际上是一个vue项目）
  • 需要编译

开始

下载vuepress

  1. npm install -D vuepress

在package.json中进入配置

  1. "scripts": {
  2.   ...
  3.   "docs:dev": "vuepress dev docs",
  4.   "docs:build": "vuepress build docs"
  5. }

新建一个docs文件夹，并且在里面加入README.md文件，在里面加入配置
home：true，代表使用vuepress默认的主题样式，其他对应的属性代表的意思，我们可以直接在下面的截图中看到
注意这个actionLink代表的是点击首页欢迎按钮进入的页面，也就是在docs下面有一个component文件夹，下面有一个numberInput.md文件

  1. ---
  2. home: true
  3. actionText: 欢迎 →
  4. actionLink: /component/numberInput
  5. features:
  6. - title: 组件库
  7.   details: 基于element-ui搭建的组件库
  8. ---

然后在docs文件夹下面，新增文件夹和文件，路径是：.vuepress/config.js，这是对整个vuepress项目进行配置的地方，配置一下（后期我们的webpack也可以在这里进行配置）

  1. module.exports = {
  2.   title: 'ui',
  3.   description: '一个我们的内部组件库',
  4.   port: '8888',
  5.   base: '/',
  6.   // 主题配置
  7.   themeConfig: {
  8.     // 头部导航条，自己定义url
  9.     nav: [{
  10.         text: '首页',
  11.         link: '/'
  12.       },
  13.       {
  14.         text: '指南',
  15.         link: '/guide/start'
  16.       },
  17.       {
  18.         text: '文档',
  19.         link: '/test'
  20.       },
  21.       {
  22.         text: 'GitLab',
  23.         link: '/t'
  24.       }
  25.     ],
  26. }

运行npm run docs:dev ，即可看到下面页面
image.png
点击欢迎按钮，我们会进入组件文档中，我们平常看vue的一些文档，会发现网站侧边是有导航的，如图：
image.png
下面我们进行导航设置，这个设置也是在config.js文件中的，其中每个组件对应的文档就是里面配置的路径，都是相对于docs文件夹的位置决定的，所以我们需要在docs文件夹下面新建component文件夹，里面就是我们每一个组件对应的md文件了

  1. // config.js
  2. themeConfig: {
  3.     sidebar: [{
  4.         title: '开发指南',
  5.         collapsable: false,
  6.         children: [
  7.           '/guide/start',
  8.         ]
  9.       },
  10.       {
  11.         title: '组件',
  12.         collapsable: false,
  13.         children: [{
  14.             collapsable: false,
  15.             children: [
  16.               '/component/numberInput',
  17.             ]
  18.           },
  19.           {
  20.             collapsable: false,
  21.             children: [
  22.               '/component/iconSvg',
  23.             ]
  24.           },
  25.           {
  26.             collapsable: false,
  27.             children: [
  28.               '/component/fileUpload',
  29.             ]
  30.           }
  31.         ]
  32.       }
  33.     ]
  34.   },

这样配置成功后，我们就可以写一个组件的文档了，请看下一篇
创建一个组件文档