Markdown写接口文档，自动添加TOC

上回说到，用Impress.js代替PPT来做项目展示。这回换Markdown来做接口文档好了。（不敢说代替Word，只能说个人感觉更为方便）当然，还要辅之以Git，来方便版本管理。

Markdown基本语法也没啥好说的，随便百度一下几分钟看懂基本的，20%的知识完成80%的任务嘛，够了。

关键在于，我有些特殊需求，以方便将Markdown作为接口文档查看。什么需求呢？

目录。这是重中之重。没有方便的TOC的话，文档长了，查看起来真是费劲。我理想中的目录是这样的：
- 根据H1（# ）、H2（## ）号标题，自动生成索引，而不是网上其它人的什么标题都生成索引，弄一堆子乱七八糟的完全没有接口文档的感觉了。
- 这个目录一定得是浮动在侧边栏的，不能说要查某个接口还得先回到页首去。
- 这个目录还应该是自动折叠的，当我不需要它时它得到一侧缩着，不能碍事。
表格样式，一定得是易读的，字体不能小，分界要明显，每行颜色要深浅交错开，表头颜色要更深。
读取要方便，不能要求大家都装一个Markdown阅读器，不然又成Word了。我要求能直接从浏览器打开阅读。但是也不能说每次都上传到Github之类的地方去看，麻烦，而且Github也不支持自定义样式。最重要的是，我并没有Github上的私有仓库。

Ok，就这些需求。个人感觉要求不高吧？呵呵，找了半天还真没找到。于是乎，自己写了一个咯：https://github.com/zhengxiaoyao0716/MarkedWithToc。

简单来说，就是一张网页。把写好的.md文件拖拽上去，然后按照以上需求生成html预览自动生成目录、黑白两种为接口文档优化过的主题，一键保存到本地。配合git做版本管理，应该会方便很多。

就这样，本次不是教程，不是学习笔记，只是一个建议和推广，给所有追求变化爱折腾的程序猿。懒得进GitHub的，直接打开这个链接即可使用：http://temp.zheng0716.com/MarkedWithToc/。注意，第一个一级标题会被无视，因为要作为文档标题嘛。

转载于:https://www.cnblogs.com/zhengxiaoyao0716/p/5914917.html

Markdown写接口文档，自动添加TOC相关推荐

springboot整合knife4j，从此告别手写接口文档
关于knife4j Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目一开始项目初衷是为了写一个增 ...
写java接口的文档工具_【java】适合写接口文档的工具，或者文本语法
由于后端与前端使用ajax交互,后端写接口文档变得非常有必要.以前我习惯用word写接口文档,但是最近与同事合作编写后端,word并不适合使用svn工具做同步,因为svn.git等无法自动合并word ...
Haroopad写接口文档简介
一.所需工具:Haroopad - The next document processor 根据自己的电脑下载安装包,我的是Haroopad-v0.13.1-win-x64.msi,安装,一路next ...
Python Swagger 接口文档自动集成平台
一安装当前virtualenv 环境下 pip install django-rest-swagger==2.2.0 在Django项目settings.py中加入插件模块 DEBUG = T ...
如何用Postman写接口文档，团队协作开发
最近为了减少对代码的侵入性,舍弃了之前一直使用的Swagger,但是showdoc写文档又比较麻烦,测试接口也不方便,于是看了一下网上的多篇关于postman写接口文档的文章,并且亲身实验后将经验结合 ...
写接口文档及生成mock数据
写接口文档及生成mock数据在web应用开发的过程中,与前端联调时总会有一些接口,需要接口文档,在接口先行的情况下,前端不能拿到实际的接口进行开发,所以就需要mock数据. 今天搜索了下,阿里在这方 ...
php怎么根据接口文档实现功能,CodeIgniter+swagger实现 PHP API接口文档自动生成功能...
一.安装swagger 1.首先需要有composer,没有的自行百度安装 2.下载swagger,打开网站https://packagist.org/packages/zircote/swagger ...
学习笔记：利用markdown写readme文档（Udacity学城）
周末逛知乎等资讯平台的时候,无意间了解到Udacity学城有一期关于利用markdown撰写readme文档的教程,想到CSDN博客也提供了markdown编辑功能,而自己到现在还不会用,看着自己写的 ...
你还在手写接口文档？来，壹哥教你一招实现在线接口文档
我们知道,现在很多项目开发都采用了前后端分离的模式.在这种模式下,前端人员开发前端相关的功能,后端人员开发后端相关的功能.那么问题来了,前端需要调用后端实现的接口进行交互,两者之间是如何进行交互的?前 ...

Markdown写接口文档，自动添加TOC

Markdown写接口文档，自动添加TOC相关推荐

最新文章

热门文章