docsify 不一样的文档工具

一、无规范不和谐

俗话说"无规矩不成方圆",但是我要说无规范不和谐,你可能觉得言重了「言重个毛」,下面就简单的说一下吧

  • 公司没有规范可以吗「那不乱了套了」
  • 人事招人没有规范可以吗「随便拿个人来就用,你估计会被人说秀逗了」
  • 团队管理没有规范可以吗「谁特么鸟你」
  • 开发人员没有文档(各种文档)可以吗「NM,连个需求文档都没有,做个毛毛,这句话不陌生吧」
  • 你没有规范能找到自己喜欢的女(男)朋友?「还不是按自己的规范和标准来衡量的」
  • 特别是开发语言,如果没有规范,你全部乱整,还有其它等等各种规范

来一个场景对话吧,以开发一个 APP 为例子来说明「纯属虚构,如有雷同那真是中奖了」,小明「开发 client」,小张「开发 server」

docsify 不一样的文档工具_第1张图片
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 不一样的文档工具_第2张图片
docsify-fecture

部分使用 docsify 文档

docsify 不一样的文档工具_第3张图片
docsify-showcase

比如阿里 weex ui 的开发文档

docsify 不一样的文档工具_第4张图片
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 接口文档吧,大概完成以后这样的

docsify 不一样的文档工具_第5张图片
sys-api

还做一个国际化「只做了英文版的--装个 B 」,直接点击上面导航的 EN 来 Look 一下

docsify 不一样的文档工具_第6张图片
sys-en

怎么样够 B 格吧 ,服务端把这个文档给出一扔,还管个毛毛呢,直接并行开发吧「还 qq 对接?,还拿嘴对接?」

docsify 目录解析

由于 docsify 的文档非常的详细,我们照着一点点的配置和编写半个小时就能入门,这里我们就把以上完成的 API 文档目录解析一下

docsify 不一样的文档工具_第7张图片
doc_folder

主页 index.html

docsify 不一样的文档工具_第8张图片
doc-index

侧边栏 _sidebar.md

docsify 不一样的文档工具_第9张图片
slide-menu

侧边栏对应的网页左边的导航页

_coverpage.md 封面

docsify 不一样的文档工具_第10张图片
logo-page

user/READMD.md

user/README.md 对应的就是 user 的主页,在这个例子中我们在此中写登录接口

docsify 不一样的文档工具_第11张图片
login-page

对应的就是我们在上图中看到登录接口「我们再来看一下,如下图」

docsify 不一样的文档工具_第12张图片
login-html

其它的 .md

其它的 getuserlist.md/getuserifno.md 都是侧边栏对应的接口界面,这里就不一一说了,和登录界面是一样的「不细说了,文档介绍的非常详细」

我们大概介绍完了所制作的文档,这里起一个抛砖引玉的作用,完了可以看 Demo 的源码「上传到 github 上,后面放出地址」

四、其它配置

可以定制主题、还有一插件列表「搜索、统计、在 github 编辑等等插件」,也可以自己开发插件等「非常丰富,我们可以看官网查看」

五、部署

我们写的文档可以部署在 GitHub Pages 上,也可以部署在所有的静态文件服务器上等

六、总结

这节我们简单介绍了一下 docsify 文档编写工具,只是起了一个抛砖引玉的作用,具体的好多玩法大家可以自行去探所,当然拿 docsify 来写笔记是非常不错的「笔者一直使用 gitbook 来写笔记」,还可以用它来写个博客啥的都是不错的

如果还不熟悉 markdown 语法的,建议现在就看一定要把它掌握了「简单又牛 B ,写个模版什么的使用 markdown 再适合不过了」

案例地址:https://github.com/tigerchain/docsifydemo


作者: TigerChain 订阅查看更多内容。
本文出自 TigerChain 侃大山
公号: TigerChain

你可能感兴趣的:(docsify 不一样的文档工具)