PHP實現markdown文檔管理工具

工做後一直在從事PHP開發, 從之前的大包大攬到如今的退居服務端寫接口, 當中接觸過幾個的接口文檔管理工具或系統, 簡單描述下:

1. showdoc, 功能全面並且簡潔, 有用戶,權限管理功能, 支持markdown, 支持導出word, 有多種文檔模板, 目錄支持兩級摺疊
2. confluence, 功能強大(權限管理, 郵件提醒, 全文搜索, 插件管理等), 重, 收費的一個文檔管理系統
3. swagger, 須要在代碼中寫大量的註釋去配合
4. readmine, 功能豐富相似confluence, 它的文檔是以txt保存的, 能夠追溯變動, 能夠全文搜索, 可是寫文檔有點痛苦, 適合任務/bug跟蹤管理等
5. gitbook, nodejs安裝, 支持markdown, 支持npm插件, 左側的可摺疊的目錄樹就須要裝插件, 也能夠裝搜索插件, 目錄是單獨的markdown文件, 我使用的時候感受從md到HTML編譯太慢(600+的文檔, 要編譯25分鐘多, 若是有增量編譯或提升編譯速度的插件還請各位賜教)

兩個月前由於項目的緣由須要一個簡單的工具來管理接口文檔, 此次就把開發過程當中的經歷記錄在這裏, 拋磚引玉~

主要目標:

1. 能夠多人編輯
2. 能夠在瀏覽器中查看
3. 有一個能夠自動展開並高亮的目錄
4. 支持多級目錄
5. 支持markdown
6. 快, 方便

解決方法:

1. 結合git就能夠實現, 正好也能夠利用git的權限管理功能
2. 須要將markdown編譯成HTML文件部署到內網
3. 由於要在瀏覽器中查看, 這裏最終選擇了接入簡單, 界面清爽, 無依賴的dtree.js (不依賴jQuery)
4. 這個功能用了樹的後根序遍歷算法實現了對多級文件的讀取(沒有用遞歸, 擔憂寫着寫着把本身繞進去), 正好dtree.js 也支持多級目錄摺疊
5. 這裏我選擇了segmentfault官方出的PHP編譯工具類,改用 parsedown (相較sf的類他沒有安全校驗, 支持單行內多個換行符)
6. 快: 編譯600多個文件, PHP用時1s左右,能夠接受, 並且支持增量編譯; 方便: 主要體如今目錄是自動生成的, 不須要單獨在編寫目錄

其中遇到的問題:

增量編譯

剛開始判斷一個md文件是否須要編譯成HTML, 是拿md文件的建立時間和最後修改時間作對比進行判斷的,
可是後來發現, 一些複製來的, 重命名的文件用這個方法就不起做用.
最後使用了一箇中間文件, 去記錄本次編譯的文件的時間, 再跟 max(建立時間, 最後修改時間)對比判斷是否須要編譯

刪除多餘文件

後續使用過程當中發現, 有些md文檔被刪除了, 可是沒有自動刪除最終編譯後的文件,
所以, 在編譯時會對md文件和最後的HTML文件求一個差集, 刪掉那些多餘的HTML文件

整合dtree.js

首先, dtree.js須要必定要求的json數據才能顯示目錄和進行展開和摺疊的交互
還有, dtree.js字體比較小, 他的圖片,樣式,腳本文件都是相對路徑, 我這裏對路徑作了相應修改, 使之改成基於當前域名的絕對路徑, 這樣部署到不一樣的域名下是不用修改dtree.js代碼的層級目錄的

組裝, 美化HTML

組裝是事先寫好HTML的頭部, 底部, 側邊欄等的HTML代碼, 而後把這些內容與編譯後的內容進行組裝, 最後再放到相應的文件夾中去
美化, 這個主要是由於markdown編譯工具並無對生成的HTML元素(例如, table, code)添加樣式, 我這裏找了一些簡潔的css樣式進行了美化

支持多級目錄

這個也是耗費了我大量腦細胞寫出來的, 大學的時候寫動態哈夫曼編碼算法的時候實現過一次樹的遍歷,
本覺得得心應手, 誰知道折騰到夜裏3點多才最終寫好, 這個功能也算是核心組件之一了吧

手動編譯太麻煩

後來發現, 每次用git commit 前要先手動在命令行裏編譯一下(php compile.php)以爲麻煩,
就給git加了一個hook, 在提交以前自動執行編譯命令, 這樣就方便多了

最後附上源代碼

源代碼(碼雲git)

使用方法(cnblog)

例子

效果圖