PHP实现markdown文档管理工具

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

1. showdoc, 功能全面并且简洁, 有用户,权限管理功能, 支持markdown, 支持导出word, 有多种文档模板, 目录支持两级折叠
2. confluence, 功能强大(权限管理, 邮件提醒, 全文搜索, 插件管理等), 重, 收费的一个文档管理系统
3. swagger, 须要在代码中写大量的注释去配合
4. readmine, 功能丰富相似confluence, 它的文档是以txt保存的, 能够追溯变动, 能够全文搜索, 可是写文档有点痛苦, 适合任务/bug跟踪管理等
5. gitbook, nodejs安装, 支持markdown, 支持npm插件, 左侧的可折叠的目录树就须要装插件, 也能够装搜索插件, 目录是单独的markdown文件, 我使用的时候感受从md到HTML编译太慢(600+的文档, 要编译25分钟多, 若是有增量编译或提升编译速度的插件还请各位赐教)

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

主要目标:

1. 能够多人编辑
2. 能够在浏览器中查看
3. 有一个能够自动展开并高亮的目录
4. 支持多级目录
5. 支持markdown
6. 快, 方便

解决方法:

1. 结合git就能够实现, 正好也能够利用git的权限管理功能
2. 须要将markdown编译成HTML文件部署到内网
3. 由于要在浏览器中查看, 这里最终选择了接入简单, 界面清爽, 无依赖的dtree.js (不依赖jQuery)
4. 这个功能用了树的后根序遍历算法实现了对多级文件的读取(没有用递归, 担忧写着写着把本身绕进去), 正好dtree.js 也支持多级目录折叠
5. 这里我选择了segmentfault官方出的PHP编译工具类,改用 parsedown (相较sf的类他没有安全校验, 支持单行内多个换行符)
6. 快: 编译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, 在提交以前自动执行编译命令, 这样就方便多了

最后附上源代码

源代码(码云git)

使用方法(cnblog)

例子

效果图