基于vue的ui组件库开发—— 06docsify是一款快速、简洁且易于上手的文档站点生成器，本文通过项目构建、导航配置

前言

前面的内容我们已经了解了一个基本的ui组件库从项目构建到发布的整个过程，虽然完成了npm 包的发布，但是如果能够提供一个文档介绍的网页给用户，那岂不是更加方便，而且这也应该是需要完成的一个重要流程。现在文档生成现在是有比较成熟的工具使用的，例如：docsify、vuepress 等都是比较常用的在线文档生成工具。本篇文章我们是通过 docsify 工具的使用详解来了解一个酷炫的在线文档是如何生成并部署的。

1. docsify 安装和启动

docsify是一款快速、简洁且易于上手的文档站点生成器，官网地址：docsify.js.org/#/zh-cn/ 使用时通过安装 docsify-cli工具，可以非常方便地创建同时在本地预览生成的文档。

npm i docsify-cli

如果想在当前的项目的根目录下创建一个目录，并初始化 docsify，可以执行下面的命令，就生成一个 docs文件目录。

docsify init ./docs

初始化成功之后可以看到在 ./docs 下创建了几个文件：

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

执行命令 docsify serve docs 启动一个本地服务器，我们可以预览当前的文档效果，在入口文件 index.html 中是通过 <div id="app">加载中...</div> 来挂载内容区域，window.$docsify 会自动识别id为app 的dom标签，如果更改了 el 的配置，需要将该元素加上 data-app 属性，便于识别，例如：

<!-- index.html -->
<div data-app id="main">加载中</div>

<script>
  window.$docsify = {
     el: '#main'
  }
</script>

2. 页面配置

2.1 配置多页面

当服务器启动后，默认渲染的是 README.md的内容，要改变页面内容，只需要修改它，保存就会自动渲染刷新，不需要重启服务。在浏览器中输入 http://localhost:3000/#/，就会展示README.md的内容

当然我们知道一个复杂的在线文档，一个单页面是肯定不够的，我们需要扩展其他的页面怎么处理呢？只需再创建一个.md 文件即可。例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

对应的访问页面如下：

docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/guide
docs/zh-cn/README.md  => http://domain.com/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide

2.2 配置侧边栏

首先修改 index.html配置文件，配置loadSidebar 选项:

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>

在 docs 目录下新增 _sidebar.md 文件，内容如下。当前的侧边栏有2层目录级别，可以通过修改 index.html配置文件的参数 subMaxLevel 控制侧边栏的目录层级的级别。侧边栏内容中可以看到每个内容区域都跟着一个路径，在预览页面时点击内容，就会跳转到指定路径的页面。

// _sidebar.md
- 开发指南
  
  - [介绍](v1.0.0/_intro.md)
    
  - [快速开始](v1.0.0/_quickstart.md)
    
  - [适配指南](v1.0.0/_flexible.md)
    
  - [定制主题](v1.0.0/_themes.md)
    
- 组件

  - 基础组件
    
  - [Icon 图标](v1.0.0/icon.md)
    
  - [Button 按钮](v1.0.0/button.md)
    
  - 业务组件
     
  - [NavBar组建](v1.0.0/nav-bar.md)

2.3 配置导航栏

在 index.html 配置导航栏参数 loadNavbar

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 2,
    loadNavbar: true
  }
</script>

如果导航内容较多，可以写成嵌套的列表，会被渲染成下拉列表的形式, 配置文件_navbar.md如下

// _navbar.md
* 版本
    * [v1.0.0](v1.0.0/)
    * [v1.0.1](v1.0.1/)
*  ｜  
* 语言切换
    * [中文](v1.0.0/)
    * [英文](v1.0.0/)

2.4 配置封面

在index.html中配置参数 coverpage 开启封面。通常封面和首页是同时出现的，设置了onlyCover为true就独立成封面。

<script>
   window.$docsify = {
      coverpage: true,
      onlyCover:true,
      loadNavbar: true,
      loadSidebar: true,
      subMaxLevel: 2
   }
  </script>

添加配置文件_coverpage.md来配置封面，在文件夹media里面放logo图片logo.jpg

// _coverpage.md
![logo](_media/img/logo.png)

# askbob_ui

> 分享技术，热爱技术


[Git 地址](https://xxxx.com)
[Get Started](v1.0.0/_intro)

// 背景图片

![](media/bg.png)

// 背景色

![color](#f0f0f0)

3. 定制化插件

3.1 搜索插件

全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。默认过期时间为一天。在index.html配置搜索插件：

<script>
window.$docsify = {
      ......
      search: {
        maxAge: 86400000,//过期时间,单位毫秒,默认一天
        paths: [], // or 'auto'
        placeholder: '请输入搜索关键字',
        noData: '没有搜到呦!',
        depth: 2
    	}
}

还需要在index.html添加js

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

3.2 剪贴板插件

在所有的代码块上添加一个简单的 Click to copy 按钮来允许用户从你的文档中轻易地复制代码。只需要在index.html中添加js:

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>

3.3 字数统计插件

在index.html添加配置

window.$docsify = {
  count:{
    countable:true,
    fontsize:'0.9em',
    color:'rgb(90,90,90)',
    language:'chinese'
  }
}

在index.html添加js,可以在页面的右上角看到字数统计

<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

4. 通过git的pages服务部署

我们知道代码托管网站 github 提供了pages 服务，通过 GitHub Pages 可以用来托管和发布网页，其实就可以作为一个简单的web服务器部署静态页面。GitHub Page的特点如下：

优点：规范、部署不限制、自由度高、配置域名不收费
缺点：国内访问速度慢、仓库不能设置私有

我们将项目代码提交 github 之后，点击 setting 进入 Pages 页面,你就会看到一行提示：Your site is published at https://xxxxxx.github.io/ ，然后在source里面选择分支，然后选择文件目录 docs，这样通过访问地址 https://xxxxxx.github.io/docs 就能打开在线文档。

上面的方式是github托管网站的部署方式，不同企业内部的代码托管仓库方式可能不一样，但是思路大同小异。