PHP實(shí)現(xiàn)markdown文檔管理工具

wpw 發(fā)布于2019-06-28 18:22 / 603人閱讀

摘要：工作后一直在從事開(kāi)發(fā)從以前的大包大攬到現(xiàn)在的退居服務(wù)端寫(xiě)接口當(dāng)中接觸過(guò)幾個(gè)的接口文檔管理工具或系統(tǒng)簡(jiǎn)單描述下功能全面而且簡(jiǎn)潔有用戶權(quán)限管理功能支持支持導(dǎo)出有多種文檔模板目錄支持兩級(jí)折疊功能強(qiáng)大權(quán)限管理郵件提醒全文搜索插件管理等重收費(fèi)的一個(gè)文

工作后一直在從事PHP開(kāi)發(fā), 從以前的大包大攬到現(xiàn)在的退居服務(wù)端寫(xiě)接口, 當(dāng)中接觸過(guò)幾個(gè)的接口文檔管理工具或系統(tǒng), 簡(jiǎn)單描述下:

showdoc, 功能全面而且簡(jiǎn)潔, 有用戶,權(quán)限管理功能, 支持markdown, 支持導(dǎo)出word, 有多種文檔模板, 目錄支持兩級(jí)折疊

confluence, 功能強(qiáng)大(權(quán)限管理, 郵件提醒, 全文搜索, 插件管理等), 重, 收費(fèi)的一個(gè)文檔管理系統(tǒng)

swagger, 需要在代碼中寫(xiě)大量的注釋去配合

readmine, 功能豐富類(lèi)似confluence, 它的文檔是以txt保存的, 可以追溯變更, 可以全文搜索, 但是寫(xiě)文檔有點(diǎn)痛苦, 適合任務(wù)/bug跟蹤管理等

gitbook, nodejs安裝, 支持markdown, 支持npm插件, 左側(cè)的可折疊的目錄樹(shù)就需要裝插件, 也可以裝搜索插件, 目錄是多帶帶的markdown文件, 我使用的時(shí)候感覺(jué)從md到HTML編譯太慢(600+的文檔, 要編譯25分鐘多, 如果有增量編譯或提高編譯速度的插件還請(qǐng)各位賜教)

兩個(gè)月前因?yàn)轫?xiàng)目的原因需要一個(gè)簡(jiǎn)單的工具來(lái)管理接口文檔, 這次就把開(kāi)發(fā)過(guò)程中的經(jīng)歷記錄在這里, 拋磚引玉~

主要目標(biāo):

可以多人編輯

可以在瀏覽器中查看

有一個(gè)可以自動(dòng)展開(kāi)并高亮的目錄

支持多級(jí)目錄

支持markdown

快, 方便

解決方法:

結(jié)合git就可以實(shí)現(xiàn), 正好也可以利用git的權(quán)限管理功能

需要將markdown編譯成HTML文件部署到內(nèi)網(wǎng)

因?yàn)橐跒g覽器中查看, 這里最終選擇了接入簡(jiǎn)單, 界面清爽, 無(wú)依賴的dtree.js (不依賴jQuery)

這個(gè)功能用了樹(shù)的后根序遍歷算法實(shí)現(xiàn)了對(duì)多級(jí)文件的讀取(沒(méi)有用遞歸, 擔(dān)心寫(xiě)著寫(xiě)著把自己繞進(jìn)去), 正好dtree.js 也支持多級(jí)目錄折疊

這里我選擇了~~segmentfault官方出的PHP編譯工具類(lèi)~~,改用 parsedown (相較sf的類(lèi)他沒(méi)有安全校驗(yàn), 支持單行內(nèi)多個(gè)換行符)

快: 編譯600多個(gè)文件, PHP用時(shí)1s左右,可以接受, 而且支持增量編譯; 方便: 主要體現(xiàn)在目錄是自動(dòng)生成的, 不需要多帶帶在編寫(xiě)目錄

其中遇到的問(wèn)題: 增量編譯

剛開(kāi)始判斷一個(gè)md文件是否需要編譯成HTML, 是拿md文件的創(chuàng)建時(shí)間和最后修改時(shí)間做對(duì)比進(jìn)行判斷的,
但是后來(lái)發(fā)現(xiàn), 一些復(fù)制來(lái)的, 重命名的文件用這個(gè)方法就不起作用.
最后使用了一個(gè)中間文件, 去記錄本次編譯的文件的時(shí)間, 再跟 max(創(chuàng)建時(shí)間, 最后修改時(shí)間)對(duì)比判斷是否需要編譯

刪除多余文件

后續(xù)使用過(guò)程中發(fā)現(xiàn), 有些md文檔被刪除了, 但是沒(méi)有自動(dòng)刪除最終編譯后的文件,
因此, 在編譯時(shí)會(huì)對(duì)md文件和最后的HTML文件求一個(gè)差集, 刪掉那些多余的HTML文件

整合dtree.js

首先, dtree.js需要一定要求的json數(shù)據(jù)才能顯示目錄和進(jìn)行展開(kāi)和折疊的交互
還有, dtree.js字體比較小, 他的圖片,樣式,腳本文件都是相對(duì)路徑, 我這里對(duì)路徑做了相應(yīng)修改, 使之改為基于當(dāng)前域名的絕對(duì)路徑, 這樣部署到不同的域名下是不用修改dtree.js代碼的層級(jí)目錄的

組裝, 美化HTML

組裝是事先寫(xiě)好HTML的頭部, 底部, 側(cè)邊欄等的HTML代碼, 然后把這些內(nèi)容與編譯后的內(nèi)容進(jìn)行組裝, 最后再放到相應(yīng)的文件夾中去
美化, 這個(gè)主要是因?yàn)閙arkdown編譯工具并沒(méi)有對(duì)生成的HTML元素(例如, table, code)添加樣式, 我這里找了一些簡(jiǎn)潔的css樣式進(jìn)行了美化

支持多級(jí)目錄

這個(gè)也是耗費(fèi)了我大量腦細(xì)胞寫(xiě)出來(lái)的, 大學(xué)的時(shí)候?qū)憚?dòng)態(tài)哈夫曼編碼算法的時(shí)候?qū)崿F(xiàn)過(guò)一次樹(shù)的遍歷,
本以為駕輕就熟, 誰(shuí)知道折騰到夜里3點(diǎn)多才最終寫(xiě)好, 這個(gè)功能也算是核心組件之一了吧

手動(dòng)編譯太麻煩

后來(lái)發(fā)現(xiàn), 每次用git commit 前要先手動(dòng)在命令行里編譯一下(php compile.php)覺(jué)得麻煩,
就給git加了一個(gè)hook, 在提交之前自動(dòng)執(zhí)行編譯命令, 這樣就方便多了

最后附上源代碼 源代碼(碼云git) 使用方法(cnblog) 例子 效果圖