php 注释 markdown,PHP实现markdown文档管理工具

工作后一直在从事PHP开发, 从以前的大包大揽到现在的退居服务端写接口, 当中接触过几个的接口文档管理工具或系统, 简单描述下:

showdoc, 功能全面而且简洁, 有用户,权限管理功能, 支持markdown, 支持导出word, 有多种文档模板, 目录支持两级折叠

confluence, 功能强大(权限管理, 邮件提醒, 全文搜索, 插件管理等), 重, 收费的一个文档管理系统

swagger, 需要在代码中写大量的注释去配合

readmine, 功能丰富类似confluence, 它的文档是以txt保存的, 可以追溯变更, 可以全文搜索, 但是写文档有点痛苦, 适合任务/bug跟踪管理等

gitbook, nodejs安装, 支持markdown, 支持npm插件, 左侧的可折叠的目录树就需要装插件, 也可以装搜索插件, 目录是单独的markdown文件, 我使用的时候感觉从md到HTML编译太慢(600+的文档, 要编译25分钟多, 如果有增量编译或提高编译速度的插件还请各位赐教)

两个月前因为项目的原因需要一个简单的工具来管理接口文档, 这次就把开发过程中的经历记录在这里, 抛砖引玉~

主要目标:

可以多人编辑

可以在浏览器中查看

有一个可以自动展开并高亮的目录

支持多级目录

支持markdown

快, 方便

解决方法:

结合git就可以实现, 正好也可以利用git的权限管理功能

需要将markdown编译成HTML文件部署到内网

因为要在浏览器中查看, 这里最终选择了接入简单, 界面清爽, 无依赖的dtree.js (不依赖jQuery)

这个功能用了树的后根序遍历算法实现了对多级文件的读取(没有用递归, 担心写着写着把自己绕进去), 正好dtree.js 也支持多级目录折叠

这里我选择了segmentfault官方出的PHP编译工具类,改用 parsedown (相较sf的类他没有安全校验, 支持单行内多个换行符)

快: 编译600多个文件, PHP用时1s左右,可以接受, 而且支持增量编译; 方便: 主要体现在目录是自动生成的, 不需要单独在编写目录

其中遇到的问题:

增量编译

刚开始判断一个md文件是否需要编译成HTML, 是拿md文件的创建时间和最后修改时间做对比进行判断的,

但是后来发现, 一些复制来的, 重命名的文件用这个方法就不起作用.

最后使用了一个中间文件, 去记录本次编译的文件的时间, 再跟 max(创建时间, 最后修改时间)对比判断是否需要编译

删除多余文件

后续使用过程中发现, 有些md文档被删除了, 但是没有自动删除最终编译后的文件,

因此, 在编译时会对md文件和最后的HTML文件求一个差集, 删掉那些多余的HTML文件

整合dtree.js

首先, dtree.js需要一定要求的json数据才能显示目录和进行展开和折叠的交互

还有, dtree.js字体比较小, 他的图片,样式,脚本文件都是相对路径, 我这里对路径做了相应修改, 使之改为基于当前域名的绝对路径, 这样部署到不同的域名下是不用修改dtree.js代码的层级目录的

组装, 美化HTML

组装是事先写好HTML的头部, 底部, 侧边栏等的HTML代码, 然后把这些内容与编译后的内容进行组装, 最后再放到相应的文件夹中去

美化, 这个主要是因为markdown编译工具并没有对生成的HTML元素(例如, table, code)添加样式, 我这里找了一些简洁的css样式进行了美化

支持多级目录

这个也是耗费了我大量脑细胞写出来的, 大学的时候写动态哈夫曼编码算法的时候实现过一次树的遍历,

本以为驾轻就熟, 谁知道折腾到夜里3点多才最终写好, 这个功能也算是核心组件之一了吧

手动编译太麻烦

后来发现, 每次用git commit 前要先手动在命令行里编译一下(php compile.php)觉得麻烦,

就给git加了一个hook, 在提交之前自动执行编译命令, 这样就方便多了

最后附上源代码

效果图