一、无规范不和谐
俗话说"无规矩不成方圆"，但是我要说无规范不和谐，你可能觉得言重了「言重个毛」，下面就简单的说一下吧
- 公司没有规范可以吗「那不乱了套了」
- 人事招人没有规范可以吗「随便拿个人来就用，你估计会被人说秀逗了」
- 团队管理没有规范可以吗「谁特么鸟你」
- 开发人员没有文档（各种文档）可以吗「NM,连个需求文档都没有，做个毛毛，这句话不陌生吧」
- 你没有规范能找到自己喜欢的女（男）朋友？「还不是按自己的规范和标准来衡量的」
- 特别是开发语言，如果没有规范，你全部乱整，还有其它等等各种规范
来一个场景对话吧，以开发一个 APP 为例子来说明「纯属虚构，如有雷同那真是中奖了」，小明「开发 client」，小张「开发 server」
chat.jpg
如此类似的事情的在需求、产品、销售、运营等等各个地方都会出现，何也--没有规范，最后导致权责不明，各干各的，反工是家常便饭，更甚者会干起架来 ...
无规范不和谐，花很小的代价获取更多大价值有时就体现在规范当中，规范最好以书面的形式「别拿嘴说，谁也不会记的」，规范的编写有多种形式，今天我们就来看看其中一个 docsify「文档网站生成工具」
二、docsify
写文档历程
规范基本上都以文档的形式出现的，写文档我们可以使用的工具实在太多了，小到记事本，大到一个综合软件太多太多了，先说一下笔者主要使用的文档编写工具，分为两个阶段「未了解 markdown 之前和之后」
- 1、最开始使用 excel、word 「未了解 markdown 之前」
- 2、后面使用 oschina 的 git readme 「基于 markdown 语法」
- 3、使用 gitbook 来编写文档或记笔记 「基于 markdown 语法」
- 4、使用 hexo 来编写文章或文档 「基于 markdown 语法」
现在我大部分使用 gitbook 来记笔记和写文档，只要把 markdown 语法熟悉了玩起这些来都是小菜，简书、csdn、掘金等自媒体平台都支持 markdown 了，markdown 一定要掌握「现在还不懂 markdown 那就太 low 了」，简单的说一下 gitbook 的流程
- 1、使用 markdown 来编写对应的文档或电子书界面
- 2、使用 gitbook build 会把 markdown 文件转化成 .html 文件
- 3、直接发布 html 文件即可「在网站上就可以浏览了」，当然你也可以把电子书转化成 pdf 来查看
gitbook 有多种玩法，有兴趣的可以看看这部分内容
docsify 简介
用官方的话来说 docsify 一个神奇的文档网站生成工具，如果看过 vue 的官方文档界面那就相当于看到了 docsify 生成的界面了「很清爽有么有」
docsify 不同于 githbook 和 hexo 它不会生成将 .md 文件化成 .html 文件，这些转化工作都是在运行时进行的
docsify 特性
docsify-fecture
部分使用 docsify 文档
docsify-showcase
比如阿里 weex ui 的开发文档
weex-ui-doc
这里就不一一列举了，可以查看 https://github.com/docsifyjs/awesome-docsify/blob/master/README.md 的 showcase 部分
三、安装并使用 docsify
安装 docsify
npm i docsify-cli -g
这样就安装完了 docsify 命令行工具「前提要安装 node」，安装完以后我们就可以使用 docsify init ./docs 初始化项目了，然后运行 docsify serve docs 就可以在本地跑一个 server 来看到对应生成的网站了
来个实例
无图无直相
我们就来一个 API 接口文档吧，大概完成以后这样的
sys-api
还做一个国际化「只做了英文版的--装个 B 」,直接点击上面导航的 EN 来 Look 一下
sys-en
怎么样够 B 格吧 ,服务端把这个文档给出一扔，还管个毛毛呢，直接并行开发吧「还 qq 对接？，还拿嘴对接？」
docsify 目录解析
由于 docsify 的文档非常的详细，我们照着一点点的配置和编写半个小时就能入门，这里我们就把以上完成的 API 文档目录解析一下
doc_folder
主页 index.html
doc-index
侧边栏 _sidebar.md
slide-menu
侧边栏对应的网页左边的导航页
_coverpage.md 封面
logo-page
user/READMD.md
user/README.md 对应的就是 user 的主页，在这个例子中我们在此中写登录接口
login-page
对应的就是我们在上图中看到登录接口「我们再来看一下，如下图」
login-html
其它的 .md
其它的 getuserlist.md/getuserifno.md 都是侧边栏对应的接口界面，这里就不一一说了，和登录界面是一样的「不细说了，文档介绍的非常详细」
我们大概介绍完了所制作的文档，这里起一个抛砖引玉的作用，完了可以看 Demo 的源码「上传到 github 上，后面放出地址」
四、其它配置
可以定制主题、还有一插件列表「搜索、统计、在 github 编辑等等插件」，也可以自己开发插件等「非常丰富，我们可以看官网查看」
五、部署
我们写的文档可以部署在 GitHub Pages 上，也可以部署在所有的静态文件服务器上等
六、总结
这节我们简单介绍了一下 docsify 文档编写工具，只是起了一个抛砖引玉的作用，具体的好多玩法大家可以自行去探所，当然拿 docsify 来写笔记是非常不错的「笔者一直使用 gitbook 来写笔记」，还可以用它来写个博客啥的都是不错的
如果还不熟悉 markdown 语法的，建议现在就看一定要把它掌握了「简单又牛 B ，写个模版什么的使用 markdown 再适合不过了」
案例地址：https://github.com/githubchen001/docsifydemo
作者: TigerChain 订阅查看更多内容。
本文出自 TigerChain 侃大山
公号: TigerChain
网友评论