bookMDViewer 完整教學

從安裝使用到原始碼解析：一款 4 MB 的跨平台 Markdown 檢視器如何做到 GFM + Mermaid + 即時編輯 + HTML 匯出。

1. 專案定位

這是什麼？

bookMDViewer 是一款輕量、完全本機的 Markdown viewer（檢視器）與 editor（編輯器），以 Tauri v2 打造。它使用作業系統內建的 WebView（而非內嵌 Chromium），因此：

核心功能一覽

• GFM rendering（GitHub Flavored Markdown 渲染）— 表格、任務清單、刪除線
• 程式碼語法高亮 — highlight.js
• Mermaid 圖表 — 延遲載入，無圖表時零成本
• TOC 大綱側欄 — 自動建立、scroll-spy（捲動偵測）高亮
• 即時編輯與預覽 — 分割編輯器 + 同步捲動
• 一鍵匯出 HTML — 自包含 HTML，含 TOC + 語法高亮 + Mermaid SVG
• 即時重載 — 檔案存檔後自動重新渲染
• 檔案關聯 — 雙擊 .md 直接開啟
• 拖放開啟 — 拖進視窗即可
• 文件內搜尋 — Ctrl+F
• 開啟檔案對話框 — Ctrl+O
• 最近開啟清單 — 記錄最近開過的檔案
• 字型縮放 — Ctrl++ / Ctrl+-（持久化）
• 深色/淺色主題 — 跟隨系統設定
• 安全 — DOMPurify 消毒 + 嚴格 CSP

2. 安裝指南

使用者安裝（直接下載）

到 Releases 頁面下載：

所有版本都需要系統 WebView（Windows 11 已預載 WebView2）。

開發者安裝

 1# 前置需求：Node.js + Rust toolchain
 2git clone https://github.com/craig7351/bookMDViewer.git
 3cd bookMDViewer
 4npm install
 5
 6# 開發模式（hot reload）
 7npm run tauri dev
 8
 9# 建置執行檔
10npm run tauri build
11# 產出：src-tauri/target/release/md-viewer.exe
12# 安裝檔：src-tauri/target/release/bundle/

啟動參數

1md-viewer.exe file.md            # 開啟並渲染
2md-viewer.exe file.md --edit     # 直接進入編輯模式
3md-viewer.exe file.md --zoom=1.5 # 整體 UI 放大（高 DPI / 無障礙）

3. 核心架構解析

3.1 技術棧總覽

flowchart TD
    User["使用者"] -->|雙擊 .md / 拖放 / Ctrl+O| App["bookMDViewer"]
    
    subgraph Frontend ["前端（TypeScript + Vite）"]
        MainTS["main.ts
594 行核心邏輯"]
        MdIt["markdown-it
GFM Rendering"]
        HlJs["highlight.js
語法高亮"]
        Mermaid["mermaid
圖表渲染（延遲載入）"]
        DOMPurify["DOMPurify
HTML 消毒"]
        CSS["styles.css
深色/淺色主題"]
    end
    
    subgraph Backend ["後端（Rust + Tauri v2）"]
        LibRS["lib.rs
檔案 I/O + 監看"]
        TauriAPI["Tauri API
invoke / listen / events"]
        WebView["系統 WebView
WebView2 / WKWebView / WebKitGTK"]
    end
    
    MainTS --> MdIt
    MainTS --> HlJs
    MainTS --> Mermaid
    MainTS --> DOMPurify
    MainTS -->|invoke| TauriAPI
    TauriAPI --> LibRS
    App --> Frontend
    App --> Backend

3.2 Markdown 渲染流程

flowchart LR
    A[".md 原始文字"] --> B["markdown-it
解析 + GFM"]
    B --> C["highlight.js
程式碼高亮"]
    B --> D["DOMPurify
HTML 消毒"]
    D --> E["DOM 更新"]
    E --> F{"含 mermaid?"}
    F -->|是| G["動態載入 mermaid.js
渲染圖表"]
    F -->|否| H["完成"]
    G --> H
    E --> I["buildToc()
建立大綱側欄"]
    E --> J["resolveImages()
解析本機圖片路徑"]

3.3 關鍵設計決策

4. 核心功能詳解

4.1 編輯模式

按 Ctrl+E 或工具列的 “Edit” 按鈕切換。特色：

• 分割編輯器：左側原始碼、右側即時預覽
• 同步捲動：左右兩欄同步捲動（比例同步）
• 即時預覽：輸入後 180ms 自動重新渲染（debounce）
• 未存檔提示：關閉時若有未存檔變更會跳出確認對話框
• 存檔：Ctrl+S，透過 Tauri invoke("write_md") 寫回磁碟

4.2 HTML 匯出

按工具列的 “Export” 按鈕，在原檔旁產生自包含的 .html 檔：

• 內含 TOC 側欄（sticky position）
• 內含 highlight.js 的語法高亮 CSS
• 內含已渲染的 Mermaid SVG（不需 mermaid.js runtime）
• 深色/淺色主題自適應
• 單一 HTML 檔，無外部依賴

4.3 Mermaid 圖表延遲載入

 1// 只有文件包含 mermaid 區塊時才動態載入
 2const diagrams = content.querySelectorAll("pre.mermaid");
 3if (diagrams.length > 0) {
 4  const mermaid = (await import("mermaid")).default;
 5  mermaid.initialize({
 6    startOnLoad: false,
 7    theme: prefersDark ? "dark" : "default",
 8    securityLevel: "strict",
 9  });
10  await mermaid.run({ nodes: Array.from(diagrams) });
11}

4.4 檔案監看與即時重載

透過 Tauri 後端監看開啟的檔案，外部編輯器（如 VS Code）存檔後自動重新渲染，無需手動重整。

4.5 鍵盤快捷鍵

5. 應用場景

場景 A：日常 Markdown 閱讀

雙擊任何 .md 檔即可漂亮渲染。適合閱讀 README、技術文件、筆記。TOC 側欄讓長文件導覽更方便。

場景 B：輕量 Markdown 編輯

不需要開 VS Code 或 Typora，直接在 bookMDViewer 中進入編輯模式，即時預覽效果。適合快速修改或撰寫短文。

場景 C：文件匯出為 HTML 分享

將 Markdown 文件一鍵匯出為自包含 HTML，可直接傳給不使用 Markdown 的同事。HTML 含 TOC、語法高亮和 Mermaid 圖表。

場景 D：技術簡報輔助

含 Mermaid 圖表的技術文件可直接在 bookMDViewer 中渲染展示，無需 PowerPoint。

場景 E：低資源環境

在記憶體有限的機器上（如老舊筆電、VM），bookMDViewer 的 ~30 MB 記憶體佔用遠優於 Electron 應用。

6. 資安掃描報告

掃描範圍

掃描結論

🟢 低風險 — 完全離線的桌面應用，無網路請求、無雲端、無遙測。HTML 渲染經 DOMPurify 消毒並套用嚴格 CSP，Mermaid 使用 securityLevel: "strict"。唯一的外部互動是讀寫本機檔案，且受 Tauri capabilities 限制。

安全亮點

• DOMPurify.sanitize() 在渲染前清理所有 HTML
• Mermaid securityLevel: "strict" 防止圖表中的 XSS
• 外部連結以系統預設瀏覽器開啟（不在 WebView 中載入）
• Tauri v2 capabilities 機制限制後端存取範圍

7. FAQ

Q1：跟 Typora / Obsidian / VS Code 的 Markdown 預覽有什麼不同？

A： bookMDViewer 的定位是極輕量的 viewer/editor。Typora 是全功能 WYSIWYG 編輯器（~100 MB），Obsidian 是知識管理工具（Electron ~200+ MB），VS Code 是通用編輯器。bookMDViewer 只有 ~4 MB，專注於「快速打開 .md 檔 → 漂亮閱讀 → 偶爾編輯 → 匯出分享」這個簡單流程。

Q2：為什麼選 Tauri v2 而不是 Electron？

A： Tauri 使用系統內建 WebView，不需要內嵌 Chromium。結果是執行檔從 ~150 MB 降到 ~4 MB，記憶體從 ~200-400 MB 降到 ~30-60 MB。代價是必須依賴系統 WebView（Windows 需要 WebView2，但 Windows 11 已預載）。

Q3：支援哪些 Markdown 語法？

A： 完整的 GFM（GitHub Flavored Markdown）：表格、任務清單、刪除線、圍欄程式碼區塊（支援語法高亮）、Mermaid 圖表。底層引擎是 markdown-it + markdown-it-task-lists。

Q4：匯出的 HTML 需要 server 才能開嗎？

A： 不需要。匯出的 HTML 是完全自包含的單一檔案，所有 CSS 和渲染後的 SVG 都內嵌在內。雙擊 file:// 即可開啟。

Q5：如何跨平台自動發佈？

A： 推送 git tag（如 git tag v1.0.3 && git push origin v1.0.3），GitHub Actions 會自動建置 Windows / macOS (Intel + Apple Silicon) / Linux 的所有安裝檔並發佈到 Release。

8. 進階技巧

8.1 自訂主題

修改 src/styles.css 中的 CSS variables：

 1:root {
 2  --bg: #ffffff;
 3  --fg: #1f2328;
 4  --accent: #0969da;
 5  --code-bg: #f6f8fa;
 6  --border: #d1d9e0;
 7}
 8
 9@media (prefers-color-scheme: dark) {
10  :root {
11    --bg: #0d1117;
12    --fg: #e6edf3;
13    /* ... */
14  }
15}

8.2 新增 markdown-it plugin

在 src/main.ts 中擴充：

1import markdownItFootnote from "markdown-it-footnote";
2
3const md = new MarkdownIt({ /* ... */ })
4  .use(taskLists, { enabled: true, label: true })
5  .use(markdownItFootnote);

8.3 高 DPI 設定

1md-viewer.exe file.md --zoom=1.5

或在應用內用 Ctrl++ / Ctrl+- 調整字型大小（設定會持久化到 localStorage）。

9. 整合進其他工作流

搭配 VS Code

在 VS Code 中編輯 Markdown，bookMDViewer 的即時重載功能會自動偵測檔案變更並重新渲染。兩個工具各司其職：VS Code 負責編輯，bookMDViewer 負責漂亮的預覽。

搭配 Git

.md 檔案關聯設定後，在 file explorer 中雙擊 repo 內的任何 Markdown 檔即可快速預覽。

搭配 quarkdown

bookMDViewer 可作為 quarkdown 編譯前的快速預覽工具 — 先在 bookMDViewer 中確認 Markdown 內容正確，再走 quarkdown 的正式排版流程。

匯出 HTML 作為交付物

bookMDViewer 的 HTML 匯出功能產出的自包含 HTML 品質高（含 TOC + 語法高亮 + Mermaid SVG），可直接作為技術文件的交付物。

10. 重點摘要 Checklist

• 理解定位：極輕量 Markdown viewer/editor，4 MB 執行檔
• Tauri v2 優勢：系統 WebView → 小體積 + 低記憶體
• 核心功能：GFM + highlight.js + Mermaid（延遲載入）+ TOC + 編輯預覽
• 安全機制：DOMPurify + 嚴格 CSP + Mermaid strict mode
• 匯出 HTML：自包含、單一檔案、雙擊可開
• 跨平台：Windows / macOS / Linux，GitHub Actions 自動建置
• 完全離線：無雲端、無遙測、無 API key
• 開發簡單：npm install && npm run tauri dev
• 啟動參數：--edit（編輯模式）、--zoom=1.5（縮放）
• MIT License：自由使用、修改、散布

11. 進一步閱讀

專案資源

• GitHub Repository
• Releases（下載頁）
• README（繁體中文）
• README (English)

相關技術

• Tauri v2 Documentation
• markdown-it
• highlight.js
• Mermaid
• DOMPurify
• Vite