php markdown 接口文档生成工具 SummerDoc
2024-10-12 04:38:30
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 服务器虚拟机配置:
server {
listen ;
server_name www.markdown.com; autoindex on;
location / {
root E:\virtualbox\PHP-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.
最新文章
- Linux杀死进程,查看进程
- 并行计算提升32K*32K点(32位浮点数) FFT计算速度(4核八线程E3处理器)
- 【Swift学习】Swift编程之旅---函数(十)
- select document library from certain list 分类: Sharepoint 2015-07-05 07:52 6人阅读 评论(0) 收藏
- Java Hour 59 JVM Heap
- pyhton读取json格式的气象数据
- PowerDesigner(五)-概念数据模型(CDM生成LDM,PDM和OOM)(转)
- C#中怎么在EXCEL中的单元格中画斜线啊 ??
- OneNote快捷键
- HDU 2222 Keywords Search (AC自动机)
- 串的模式匹配——Brute-Force算法
- JAVA EE 项目经常使用知识 之AJAX技术实现select下拉列表联动的两种使用方法(让你真正理解ajax)
- .NET Core: 在.NET Core中进行单元测试
- 金融量化分析【day112】:股票数据分析Tushare2
- Python3练习题 021:递归方法求阶乘
- Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test java.lang.IllegalStateException
- git flow 使用步骤
- bootstrap图片上传功能
- Ubuntu 16.04安装Pycharm2017.1.1
- day26 python学习 对象的接口,封装,私用属性 property