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.