PHP實現markdown文檔管理工具

wpw 發布于2019-06-28 18:22 / 596人閱讀

摘要：工作后一直在從事開發從以前的大包大攬到現在的退居服務端寫接口當中接觸過幾個的接口文檔管理工具或系統簡單描述下功能全面而且簡潔有用戶權限管理功能支持支持導出有多種文檔模板目錄支持兩級折疊功能強大權限管理郵件提醒全文搜索插件管理等重收費的一個文

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

showdoc, 功能全面而且簡潔, 有用戶,權限管理功能, 支持markdown, 支持導出word, 有多種文檔模板, 目錄支持兩級折疊

confluence, 功能強大(權限管理, 郵件提醒, 全文搜索, 插件管理等), 重, 收費的一個文檔管理系統

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

readmine, 功能豐富類似confluence, 它的文檔是以txt保存的, 可以追溯變更, 可以全文搜索, 但是寫文檔有點痛苦, 適合任務/bug跟蹤管理等

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

兩個月前因為項目的原因需要一個簡單的工具來管理接口文檔, 這次就把開發過程中的經歷記錄在這里, 拋磚引玉~

主要目標:

可以多人編輯

可以在瀏覽器中查看

有一個可以自動展開并高亮的目錄

支持多級目錄

支持markdown

快, 方便

解決方法:

結合git就可以實現, 正好也可以利用git的權限管理功能

需要將markdown編譯成HTML文件部署到內網

因為要在瀏覽器中查看, 這里最終選擇了接入簡單, 界面清爽, 無依賴的dtree.js (不依賴jQuery)

這個功能用了樹的后根序遍歷算法實現了對多級文件的讀取(沒有用遞歸, 擔心寫著寫著把自己繞進去), 正好dtree.js 也支持多級目錄折疊

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

快: 編譯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) 例子 效果圖

云服務器 GPU云服務器實現代碼管理文檔 php文檔工具 php文檔管理源碼 php實現合同管理

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/28204.html

Wizard 開源文檔管理系統1.0發布啦

摘要：總結如果你在為公司尋找一款開源免費的開發文檔文檔管理工具，不妨考慮一下項目，一定不會讓你失望的。 Wizard 是一款開源文檔管理系統，項目地址為 https://github.com/mylxsw/wizard。這個項目是我在2017年就開始開發的，起初只是想做一款能夠在公司內部把Swagger文檔管理起來的工具，但在這近兩年的時間里，一直斷斷續續的為其添加各種功能，現在終于下決...

cod7ce 2019-07-01 12:44 評論0 收藏0
【譯】PHP:40+開發工具推薦

摘要：今天，就為開發者介紹個方便的工具。對開發者來說，是一個非常有用的工具，它提供了超過個有用的函數。該工具檢查輸入源代碼和報告任何違反給定的標準。框架是一個開發的工具。它側重于安全性和性能，絕對是最安全的開發框架之一。 PHP是為Web開發設計的服務器腳本語言，但也是一種通用的編程語言。超過2.4億個索引域使用PHP，包括很多重要的網站，例如Facebook、Digg和WordPress。...

dreambei 2019-07-01 12:12 評論0 收藏0
常用 composer 包推薦

摘要：名稱用途說明說明地址簡單易用的請求庫官網地址功能強大的請求庫文檔輕量級配置加載類支持多種配置格式簡單的緩存類提供多種緩存驅動數字生成類似優酷視頻支持多語言支持加鹽生成官網地址網站地圖生成器簡單易用數據庫操作類支持各種常見數據庫文檔生成名稱用途說明說明地址 mashape/unirest-php 簡單易用的HTTP請求庫官網地址 guzzlehttp/guzzle ...

Tamic 2019-06-27 15:03 評論0 收藏0
開箱即用-簡潔實用的ImgURL圖床相冊程序和Zdir目錄列表程序(文件管理器）

摘要：本篇文章就來分享一下兩款開箱即用上手容易的圖床相冊程序和在線文件管理器目錄列表程序，由好友開發并維護，非常適合個人站長用作圖床相冊和文件下載分享。雖然說現在照片還有文件存儲等都可以上傳到網盤中，但是國內的網盤與國外的網盤存儲還有點不一樣。以百度網盤與Dropbox對比為例，百度網盤頂多算是一個個人用來存放私人照片和文件的網絡硬盤，如果用來分享的話很容易被百度限制或者取消下載。很多的個人站長為...

番茄西紅柿 2021-07-30 14:58 評論0 收藏2637
開源的api文檔管理系統

摘要：國外的話國內的國內開源的非常好用的一款文檔管理系統，安裝也非常方便，只需將源代碼放到項目目錄下自動安裝運行即可，不要要注意版本必須大于界面簡潔功能強大的阿里的接口管理工具，開源免費，接口自動化，數據自動生成，自動化測試，企業級管理。在項目中，需要協同開發，所以會寫許多API文檔給其他同事，以前都是寫一個簡單的TXT文本或Word文檔，口口相傳，這種方式比較老土了，所以，需要有個api...

zsirfs 2019-06-27 14:58 評論0 收藏0