小小的改变，大大的化

基于docsify进行文档管理的内部分享

一、培训目的

通过近期与其他开发团队的沟通交流，发现他们对接口文档的管理思路比较先进、查阅方便等；因此，有必要学习借鉴其他开发团队的接口文档管理思路，通过研究发现他们使用的是docsify进行接口文档的管理，在业余时间对docsify进行了一个简单的研究，抽出一定的时间为大家做一个简单的内部分享，本次分享的主要目的如下：

（1）提升开发团队接口文档管理水平；
（2）方便团队与其他项目组的沟通、交流；
（3）提高接口文档的实用性、高效性；
（4）开发人员可以更加快速的查询等；

在正式分享前，我们先看一下以下几个接口查询效果，具体如下图所示：

docsify

微信小程序API

支付宝小程序

百度小程序

二、培训内容

2.1概况说明

本次培训，主要包含如下内容：

（1）docsify介绍及安装；
（2）MD文件基本语法介绍；
（3）文档管理demo演示；
（4）逐步掌握接口文档的编写；

2.2docsify介绍

2.2.1docsify介绍

docsify是一个文档生成工具，它直接加载 Markdown 文件并动态渲染，同时还可以生成封面页。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。 docsify是由现饿了么前端团队@elemeFE的cinwell.li编写的一套文档站点生成框架，github上已有3k+ star，这款框架和其他框架如gitbook等相比，最大的区别就在于docsify不是静态生成html，而通过动态请求markdown编译生成html。

2.2.2docsify特点

（1）无需构建无需编译，写完markdown文档直接发布
（2）容易使用并且轻量 (~18kB gzipped)
（3）智能的全文搜索
（4）提供多套主题
（5）丰富的 API
（6）支持 Emoji
（7）兼容 IE10+
（8）支持 SSR (example)
（9）快速上手

2.2.3文档规范的好处

（1）目录、说明清晰可见；
（2）便于开发人员预览查询；
（3）文档更加方便维护；

2.2.4官方网址

对于具体的学习资料，大家可以参考官方网站。

https://docsify.js.org/#/zh-cn/quickstart

2.2.5其它主流文档管理

目前市面上有大致这么几款主流的文档生成站点，分别为docsify、gitbook、Phenomic等，可帮助用户快速搭建文档站点。其它三种在此不再赘述，喜欢的人员可以自行了解；需要说明的是，目前微信相关的接口文档使用的是gitbook进行编写的。

2.3安装教程

2.3.1root安装

推荐安装 docsify-cli 工具，可以方便创建及本地预览文档网站。在安装docsify-cli之前需要确保您首先安装node。

npm i docsify-cli -g

2.3.2普通用户下初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。

docsify init ./docs

2.3.3开始写文档

初始化成功后，可以看到 ./docs 目录下创建的几个文件

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

直接编辑 docs/README.md 就能更新网站内容，当然也可以写多个页面。

2.3.4启动服务

运行一个本地服务器通过 docsify serve 命令可以方便的预览效果，而且提供 LiveReload 功能，可以实时的预览。默认访问 http://localhost:3000 。

docsify serve docs

如果需要启动其他端口，可以直接在后面增加-p 4000表示启动端口为4000

更多命令行工具用法，参考 docsify-cli 文档。

项目启动

预览效果

2.3.5手动初始化

如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 index.html 文件。

index.html文件内容具体如下：

2.3.6侧边栏

为了有侧边栏，那么你可以创建你自己的_sidebar.md：

首先，你需要设置loadSidebar为true，详细信息可在配置段落中找到。

2.3.6.1 index.html配置如下所示：

2.3.6.2侧边栏md配置

创建_sidebar.md：



- [Home](/) - [Guide](guide.md)

2.3.7完整demo示例

index.html详细配置示例如下所示：




  
  Document

三、其它扩展

搭建公司内部文档管理平台，修改完毕后推送至远端自动刷新，考虑到时间问题，后续再做详细介绍。

3.1依赖环境

Docsify、GitLab、Jenkins 版本无要求

3.2运行环境

CentOS Linux release 7.3.1611

四、培训目标

通过本次内部培训，希望达成以下目标：

（1）对docsify文档管理有一定的了解和掌握；
（2）对MD文件的基本语法有一定的了解和掌握；
（3）开发人员后期定义接口规范逐步使用docsify的方式进行编写，文档实时自动刷新；
（4）对内部的接口文档管理等工作有一定的提高；

image7.png

image8.png

docsify学习笔记（二）2019-05-25