MadEdit 重製版支援 Markdown 預覽:一個連假,還順手開發了 fermaid
這幾天連假,原本只是想替我正在用 Rust 重製的 MadEdit 加上一個 Markdown 預覽功能,沒想到一路寫下去,竟然另外開發了一套純 Rust 的 Mermaid 圖表渲染引擎 fermaid。
最後再整合幾個現有的 Rust 套件,把 Markdown 文件、表格、圖片以及 Mermaid 圖表整合進 MadEdit 的預覽視窗。原本以為只是增加一個功能,結果變成兩個開源專案一起推進。
從 MadEdit 的 Rust 重製版開始
MadEdit 原本是一套使用 C++ 與 wxWidgets 開發的文字、欄塊及十六進位編輯器。我一直很喜歡它的功能,因此決定使用現代 Rust 語言,搭配 egui / eframe 圖形介面框架,重新打造跨平台的 MadEdit。
這個版本保留文字編輯器的核心定位,同時整合語法突顯、多種字元編碼、Hex 編輯以及其他實用功能。
不過,現在使用 Markdown 記錄技術文件、系統設計與開發筆記的機會越來越多,如果編輯器只能看到 Markdown 原始碼,總覺得少了一點什麼。
因此,這次想增加的功能很明確:直接在 MadEdit 裡預覽 Markdown,不需要另外開啟瀏覽器。
Markdown 預覽其實不難,難的是 Mermaid
Rust 已經有不錯的 Markdown 相關套件,因此一般 Markdown 文件並不需要從頭開發。
這次主要使用:
egui_commonmark:直接在 egui 介面中繪製 Markdown 預覽內容。
pulldown-cmark:解析 Markdown 語法。
egui_extras:協助處理 SVG 等圖形資源。
resvg:將 SVG 圖形轉成適合 GUI 顯示的點陣影像。
透過這些套件,Markdown 的標題、段落、清單、程式碼區塊、表格及圖片等內容,都可以直接在應用程式中呈現。
但我希望 Markdown 裡面常用的 Mermaid 圖表也能直接顯示。
Mermaid 可以用文字描述流程圖、時序圖、類別圖、狀態圖等各種圖表,非常適合系統設計文件。不過,官方 Mermaid 主要是 JavaScript 生態系統,典型的渲染方式需要 JavaScript 執行環境。
對一個採用 Rust 與 egui 開發的原生桌面編輯器來說,為了顯示幾張圖,就額外引入 JavaScript Runtime、Node.js 或 Headless Browser,實在不是我想要的方向。
既然 MadEdit 的重製目標就是輕量、原生、跨平台,我希望 Mermaid 的處理方式也能符合相同的設計理念。
於是,我開始尋找純 Rust 的解決方案。
於是 fermaid 就誕生了
研究之後,我找到 Obsidian 團隊相關的開源專案 pele。這是一套輕量的 TypeScript Mermaid 渲染器,具有自己的版面配置與視覺風格。
我決定以 pele 的演算法與設計為基礎,將它移植到 Rust,並持續擴充 Mermaid 語法的支援能力。
這就是 fermaid 的由來。
fermaid 的目標很直接:使用純 Rust 將 Mermaid 原始文字渲染成 SVG,不依賴 JavaScript、Node.js 或無頭瀏覽器。
它是一個可以獨立使用的 Rust Library,也提供 CLI 工具,不需要依附 MadEdit。
經過這幾天的開發,fermaid 已經推進至 0.5.0 版本。依照目前專案 README,已涵蓋 Mermaid 12.2.0 的各類圖表,包括流程圖、時序圖、類別圖、ER Diagram、Gantt Chart、Mind Map、Sankey、C4、Architecture Diagram 等。
這裡要特別強調的是,涵蓋所有圖表類型並不代表每一項語法和官方 Mermaid 都已經百分之百相容。fermaid 目前仍屬於 Alpha 階段,各類圖表的具體支援範圍都列在 README 裡。
除了 Mermaid 的語法相容性,我也希望它具備以下特色:
純 Rust、同步執行,Library 本身不進行檔案 I/O。
相同輸入與設定能產生相同的 SVG 輸出。
支援亮色與暗色配色,以及字型調整。
可設定輸出寬度,讓圖表配合宿主程式版面。
針對不可信輸入,限制內容大小、巢狀深度,並處理連結與樣式的安全性。
將圖表產生功能做成可重複使用的函式庫。
這樣的設計除了可以用於 MadEdit,未來其他 Rust 應用程式也可以直接引用。
SVG 的相容性也是一個坑
fermaid 可以產生 SVG 之後,事情還沒有結束。
原本 SVG 的配色設計使用 CSS Variables,例如 var(--fermaid-fg),這在支援 CSS 自訂屬性的環境中相當方便。
但實際整合 MadEdit 時,使用的 resvg 並不支援這種 CSS Variable 的解析方式,造成圖表配色無法正確顯示。
因此,在 fermaid 0.5.0 加入了 RenderOptions::palette,讓輸出的 SVG 可以直接寫入明確的顏色值,而不是依賴 CSS Variables。
這不只解決了 MadEdit 的顯示問題,也改善了 fermaid 在 resvg、librsvg 等 SVG Renderer 中的相容性。
中文顯示同樣需要處理。SVG 的字型選擇、中文字寬及實際繪製效果,和一般文字介面的處理方式不完全相同,因此也針對 CJK 字型做了調整。
這些細節看起來不大,但真正整合到桌面 GUI 時,往往就是影響使用體驗的地方。
回到 MadEdit:完成 Markdown 預覽
有了 fermaid,再加上既有的 Markdown 套件,終於可以把整個預覽功能串起來。
實際處理流程大致如下:
從 MadEdit 目前的編輯文件取得 Markdown 內容。
使用 Markdown 解析與顯示套件呈現一般文字、清單、表格、圖片及程式碼區塊。
遇到 Mermaid 圖表內容時,交給 fermaid 渲染為 SVG。
再透過 resvg 將 SVG 轉成可顯示的圖像。
最後在 egui 的 Markdown 預覽區中呈現結果。
為了讓預覽真正好用,也陸續加入幾個介面功能。
三種預覽模式
目前支援獨立視窗、左右並排、上下並排三種模式。
左右並排適合同時修改 Markdown 原始碼並查看結果;上下並排則可以依照螢幕比例與個人習慣選擇。並排模式也支援同步捲動,切換時會先以編輯區的一半作為預覽尺寸,再讓使用者自行調整。
每個分頁獨立保存預覽狀態
MadEdit 支援同時開啟多個檔案,因此 Markdown 預覽不能只有一個全域開關。
現在每個分頁都可以保存自己的預覽狀態,切換檔案時會跟著切換;而且只有目前檔案屬於 Markdown 時,才會提供對應的預覽功能。
亮色與暗色主題
Markdown 預覽也配合應用程式主題調整,採用比較清楚的高對比配色。
此外,也修正了多個 Markdown 表格因為共用 egui Grid ID,導致欄寬錯亂及文字互相覆蓋的問題。
這些都是實際使用過程中才會遇到的細節。
效能最佳化:不要為了顯示一張圖載入所有字型
整合 Mermaid 圖表後,還遇到一個值得記錄的效能問題。
原本使用 egui_extras 的 SVG 文字處理功能時,可能會載入大量系統字型。為了顯示一張 Mermaid 圖表,沒有必要付出這麼大的成本。
因此,後來改成自訂的 DiagramLoader,直接讓 resvg 使用 MadEdit 已透過 fontique 載入的介面字型,挑選適合圖表顯示的 CJK 後備字型。
這樣就不需要為了 SVG 圖表額外建立一套包含大量系統字型的資料庫。
這也是我喜歡自己掌握程式架構的原因:當功能能夠正常運作之後,還可以繼續針對資源使用與效能進行調整,而不是只能接受套件的預設行為。
一個功能,變成兩個開源專案
回頭看這次連假的開發過程,其實還滿有趣的。
一開始只是要在 MadEdit 裡面增加 Markdown 預覽,結果因為 Mermaid 的 Rust 原生渲染需求,另外衍生出 fermaid 這個獨立專案。
接著又花時間處理 SVG 配色、中文字型、圖形載入效率、Markdown 表格排版,以及預覽區與編輯器之間的互動。
不過,我認為這樣的拆分是值得的。
MadEdit 專心做好文字編輯器,fermaid 專心做好 Mermaid 圖表渲染。 兩個專案各自有清楚的責任,也方便持續維護與擴充。
這讓我體會到 Rust 生態系統逐漸成熟的好處。像 Markdown 解析、GUI 顯示與 SVG 處理,都有現成的套件可以組合;只有缺少的核心部分,才需要自己開發。
未來我會繼續改善 MadEdit 的使用體驗,也會持續強化 fermaid 與 Mermaid 官方語法的相容程度。
目前 fermaid 還在 Alpha 階段,歡迎有興趣的朋友一起測試,或透過 GitHub Issue 提供意見。
專案原始碼
MadEdit — 使用 Rust 與 egui 重製的跨平台文字/欄塊/Hex 編輯器
https://github.com/tenyi/MadEdit
fermaid — 純 Rust 的 Mermaid to SVG 渲染引擎
https://github.com/tenyi/fermaid
fermaid 也已經發布至 crates.io:
https://crates.io/crates/fermaid
最後也要感謝原版 MadEdit、MadEdit-Mod,以及 Obsidian pele 與 Mermaid 的開源貢獻者。正因為有這些開源專案,才能讓原本的一個小功能,逐步延伸成更完整的成果。
這個連假雖然幾乎都在寫程式,但看到 Markdown 和 Mermaid 圖表終於可以直接在自己的 MadEdit 裡面預覽,還是很有成就感。

留言