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 服务器虚拟机配置:

server {
        listen       80;
        server_name  www.markdown.com;
        
        autoindex on;
        location / {
            root E:virtualboxPHP-Summer-Doc\_book;
            fastcgi_index  index.html;
        }

    }

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.