2017年9月18日 19:20:22 星期一
因工作需要, 用PHP写了一个管理接口文档的小工具, 下边介绍一下:
浏览器展示的效果:
例子(http://doc.hearu.top/)
项目模块说明:
- 左侧目录树: dtree.js 不依赖其他js
- Markdown转html: segmentfault社区开发的PHP工具 parsedown (一个国外的PHP类)
- 遍历md文件生成左侧目录树所需的数据: 利用树的后根序遍历算法读取文件夹的PHP类(自己开发, 暂未发现bug)
特点描述:
- 左侧目录会根据当前页面的不同, 自动展开并高亮
- 目录是根据文件夹/文件名自动生成的, 无需另外编写
- 使用markdown编写, 只用编写主体内容
- 风格类似github, 鼠标放在表格的行上时会高亮
- 若表格内换行需要手动写 <br>
- 文档的最下边显示最后编辑时间
- 手机(自测用的4.7寸浏览器)可自适应缩小
使用说明:
- 需要安装 PHP 最好是7.1+以上的版本
- 将md文件放入src目录里, 按照自己的项目命名文件和文件夹(这些名字就是最终生成的左侧树形目录的名字)
- 进入根目录, 运行命令: php compile.php 之后就可以在_book目录里看到编译好的html文件了
- 在web服务器中搭建一个虚拟机(比如: doc.abc.com), 并将根目录设置为 _book, 重启后在浏览器里访问
注意:
- _book目录里的dtree目录是事先写好的css和js, 对dtree的源文件有一些简单的改动,
- 如果不小心删掉了, 可以到根目录里解压dtree.zip, 复制到_book文件夹中
- 如果想重新编译所有文件, 可以删掉根目录下的 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.
所有评论(0)