php markdown 接口文档生成工具 SummerDoc

2017年9月18日 19:20:22 星期一

因工做须要, 用PHP写了一个管理接口文档的小工具, 下边介绍一下:

浏览器展现的效果:

项目地址:(码云)

例子(http://doc.hearu.top/)

项目模块说明:

1. 左侧目录树: dtree.js  不依赖其余js
2. Markdown转html: segmentfault社区开发的PHP工具 parsedown  (一个国外的PHP类)
3. 遍历md文件生成左侧目录树所需的数据: 利用树的后根序遍历算法读取文件夹的PHP类(本身开发, 暂未发现bug)

特色描述:

1. 左侧目录会根据当前页面的不一样, 自动展开并高亮
2. 目录是根据文件夹/文件名自动生成的, 无需另外编写
3. 使用markdown编写, 只用编写主体内容
4. 风格相似github, 鼠标放在表格的行上时会高亮
5. 若表格内换行须要手动写 <br>
6. 文档的最下边显示最后编辑时间
7. 手机(自测用的4.7寸浏览器)可自适应缩小

使用说明:

1. 须要安装 PHP 最好是7.1+以上的版本
2. 将md文件放入src目录里, 按照本身的项目命名文件和文件夹(这些名字就是最终生成的左侧树形目录的名字)
3. 进入根目录, 运行命令: php compile.php  以后就能够在_book目录里看到编译好的html文件了
4. 在web服务器中搭建一个虚拟机(好比: doc.abc.com), 并将根目录设置为 _book, 重启后在浏览器里访问

注意:

1. _book目录里的dtree目录是事先写好的css和js, 对dtree的源文件有一些简单的改动, 
2. 若是不当心删掉了, 能够到根目录里解压dtree.zip, 复制到_book文件夹中
3. 若是想从新编译全部文件, 能够删掉根目录下的 last_compile_time.log 文件, 否则, 程序只会编译最新修改的文件

小技巧:

若是不想每次提交前都手动执行 `php compile.php` 命令去编译md文件, 能够利用 Git 或 SVN 的 hook 功能去自动执行这个命令:

下边以 小海龟git为例, 给git加hook脚本:

 2018-2-10 15:51:28 星期六 更新

nginx 服务器虚拟机配置:

 1 server {
 2         listen       80;
 3         server_name  www.markdown.com;
 4         
 5         autoindex on;
 6         location / {
 7             root E:\virtualbox\PHP-Summer-Doc\_book;
 8             fastcgi_index  index.html;
 9         }
10 
11     }

2018-2-9 15:32:18 星期五 更新

由于sf出的md解析器在处理单行多个 <br> 的时候会间隔处理, 因此替换了另外一款解析器类 parsedown.php 

这个比较快, 但他官方说明没有进行安全校验, 若是担忧安全问题要使用其余插件帮助处理一下, 如下是官方说明

Security

Parsedown does not sanitize the HTML that it generates. When you deal with untrusted content (ex: user comments) you should also use a HTML sanitizer like HTML Purifier.