markmap 開源工具：把 Markdown 筆記直接變成互動心智圖

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

打開大多數心智圖軟體，你看到的是一塊畫布：新增節點、拉線、調位置，圖是「畫」出來的。可是如果你平常就用 Markdown 寫筆記，你的大綱本身已經是一棵樹，一級標題是主幹，二級標題是分支，縮排的清單是葉子。把這棵樹再手動畫一次，等於同時養兩份遲早會走版的東西，改了筆記忘記改圖，圖就從「輔助思考」變成「第二個真相來源」。

markmap 站在畫布的另一邊。它不給你畫布，只問你要 Markdown。我在 Mac 上實際跑了它的命令列工具：一則 272 位元組的筆記，第二次執行只花 0.7 秒左右，就變成一張可以摺疊分支、可以縮放、可以傳給別人看的互動心智圖。這是 GitHub 上 13,175 顆星的開源專案，MIT 授權，用 TypeScript 寫成，名字就是 Markdown 加 mindmap 的組合詞。

畫圖派工具解決的問題，跟這裡要的不一樣

先劃清兩種需求。你想要「從零構思一張圖」，需要的是畫布式編輯器，例如 TechMoon 先前介紹過的 SimpleMindMap 開源心智圖編輯器和帳號與資料邊界劃得很清楚的 ZhiMap，它們的強項是拖曳、排版、插入圖示，把腦中零散的念頭逐步長成圖。

另一種需求是「我已經有文字了，想看它的結構」。上課筆記、讀書大綱、產品規劃、開會記錄，這些內容的層級關係早就在標題和縮排裡寫好了，再畫一次只是勞動。markmap 只處理這一種：它讀你的 Markdown，把樹畫出來，就這樣。輸入是文字，輸出是圖，中間沒有畫布，也沒有「兩份真相」的同步問題，因為真相只有你那份 .md 檔。

純文字還附帶一串心智圖檔案沒有的好處：.md 檔可以被 grep 搜尋、被版本控制追蹤、被任何編輯器打開，團隊協作時改了哪一行一目了然。多數心智圖軟體存的專屬檔案格式，離開那套軟體就動彈不得。把圖當成文字的其中一種讀法，別讓它變成另一份需要同步的資料，是這類工具整組設計的起點。

一行指令的實測：餵什麼、吐什麼

實測環境是 Mac 加 Node.js，透過 npx 直接執行，不必先把工具裝進系統，前提當然是電腦上已經有 Node.js 環境，寫前端的人幾乎都有，沒有的人可以走後面提到的免安裝入口：

npx -y markmap-cli@latest sample-note.md -o sample-note.html --no-open

第一次執行因為要下載相依套件，整趟約 10 秒；之後同樣的筆記再跑一次，0.7 秒左右就結束。輸出是一個 3,359 位元組的 HTML 檔。

把這個檔案解剖開看，結構很誠實：一個空的 <svg> 畫布、三個從 CDN 載入的腳本（資料視覺化函式庫 d3 的 7.9.0 版、markmap-view、markmap-toolbar），再加上一段行內 JSON，也就是你的筆記被轉換成的樹狀資料。那段 JSON 的根節點帶著 content 與 children 欄位，一層層往下就是你的標題與清單。瀏覽器打開後，心智圖是這些腳本當場畫出來的，下圖是我本機渲染的結果，輸入是三層的產品發布筆記，分支依層級配色，摺疊控制列在右下角。

Pin

互動功能都在圖上：點節點可以收合整個子樹，收合是簡報時很好用的聚焦手段，例如把「開發」底下全部收起來，先跟聽眾講完「前置研究」與「行銷」再展開；滾輪縮放；那條工具列有放大縮小、全部展開，以及深色模式切換。命令列還附了幾個順手的參數：--no-toolbar 可以把工具列整個拿掉，做成乾淨的嵌入頁面；--watch 會盯著來源檔，你一存檔輸出就跟著更新，不過官方在說明裡明講這是給開發階段用的，不是正式的生產流程。

拿我實際餵進去的那則筆記當例子：根節點是「產品發布計畫」，三個主枝是前置研究、開發、行銷；「使用者訪談」底下再分出深度訪談與問卷，「技術選型」底下分出前端框架與資料庫。整棵樹從文字到圖，中間沒有我做過任何布局決定，位置、曲線、配色都是它算出來的，這正是文字派要的體驗。

把檔案傳給別人之前，先想清楚網路這件事

測試時挖出頭一個反直覺的地方：預設輸出的 HTML，渲染程式全部放在 CDN 上，檔案裡只有殼和資料。我把瀏覽器的網路整個擋掉再開啟這個檔案，心智圖區域是空的，一個節點都沒畫出來。換句話說，把這個檔案傳給正在飛機上、或公司內網封鎖外部 CDN 的同事，對方看到的接近空白。

工具自己知道這件事，所以提供了 --offline 參數。加上之後，所有程式會內嵌進單一 HTML 檔，實際輸出 345,690 位元組（約 338 KB），約是預設版的百倍大小，但在同樣無網路的環境開啟，圖完整渲染，連工具列都正常。怎麼選很清楚：放在網路上給人看，用輕量的預設檔；要寄出去、帶著走或長期歸檔，加 --offline。

轉換規則：哪些語法會上圖，哪些會被丟掉

另一個值得先知道的行為，是它對 Markdown 語法的取捨。我另外準備了一份塞滿各種語法的筆記去轉換，再解析輸出的樹狀資料，規則比想像的有個性。

會變成分支的：各級標題，以及深度縮排的清單，實測七層巢狀全部上圖，一層不少。節點內容裡，連結會保留成可點擊的元素，粗體斜體也照樣保留，也就是說你可以在節點上放參考連結，看圖的人直接點。比較意外的是程式碼區塊和表格，它們不會被丟掉，而是整塊塞進節點內容，變成那個分支的一部分，展開才看得到。

會被丟掉的：引言。用 > 開頭的那段文字，在輸出的樹裡完全找不到，對應的分支下什麼都沒有。如果你的筆記習慣把重點語句放進引言，這些內容上不了圖。維護者的常見問答也交代了一個上限：標題語法本身最多六層，這是 Markdown 與 HTML 的固有限制，想畫更深的結構要改用縮排清單，正好跟上面的實測對上。

對使用者的意義很實際：想讓內容出現在圖上的，就用標題和清單寫；引言拿來放本來就不需要上圖的補充資料；超過六層的深結構，交給縮排清單去疊。

圖是瀏覽器當場畫的，這個設計有代價

看懂它的專案結構，就會明白輸出為什麼長這樣。這個專案把功能拆成八個套件，住在同一個倉庫裡：markmap-lib 負責把 Markdown 解析成樹狀資料，markmap-view 搭配 d3 負責把樹畫成 SVG，markmap-toolbar 是那條工具列，markmap-cli 是命令列包裝，旁邊還有給網頁直接內嵌用的 autoloader 等週邊。拆得這麼細的用意，是讓網站開發者可以只取需要的部分，把心智圖功能裝進自己的頁面。

一般使用者只需要知道流程：Markdown 先被轉成樹狀 JSON，瀏覽器端的程式再把它畫成 SVG，節點文字靠 SVG 裡嵌 HTML 的 foreignObject 技術呈現。這套設計的代價，開發者自己在 2026 年 6 月的架構追蹤議題裡寫得很白：核心引擎跟瀏覽器 DOM 綁得太緊，沒辦法直接在 Node.js 或伺服器端出圖，而 foreignObject 在不同瀏覽引擎間的尺寸行為不一致，Safari 尤其明顯。這解釋了輸出檔為什麼必須帶著腳本在瀏覽器裡渲染，也解釋了某些環境下節點文字看起來會跑版的原因。

想調外觀的話，Markdown 檔開頭的前置資料可以放 markmap 設定區塊，例如把整棵樹改成單一色系：

---
markmap:
  color: blue
---

選項清單在文件裡的 JSON 選項頁列得清楚，除了配色，還有顏色凍結層級（把配色固定到指定深度以下）等控制。用 VSCode 擴充的人也可以把這些選項設成預設值，不必每個檔案都寫一次。

生態很大，npm 版本卻停了一年多

這個專案的周邊比我預期的大。VSCode 市集的官方擴充功能有 267,595 次安裝、30 則評分平均 5.0，2026 年 9 月還有版本更新。README 上列的整合清單還包括 Open VSX、Vim 與 Neovim 的兩套外掛、Emacs 的 eaf-markmap、給 AI 助理用的 MCP 伺服器，以及讓 AI 代理直接產圖的技能包（這份清單是作者自己列的，我沒有逐一安裝驗證）。專案緣起也寫在 README 裡：受到 dundalek 同名專案的啟發，由維護者 gera2ld 做成現在的規模。

版本狀態要分開看。npm 上的最新版 0.18.12 停在 2025 年 6 月 12 日，到 2026 年 10 月中已經超過一年沒發新版；不過原始碼倉庫的 master 分支 2026 年 9 月 12 日還有修復提交，倉庫開著的議題連同合併請求共 60 個，日常維護看得到脈搏。我的判讀是成熟工具的穩定期，還不到棄案的程度，但如果你期待快速迭代的新功能，這裡不會有。

引言不上圖，右到左文字等了快五年

這個專案現階段拿得到的硬邊界，集中在這裡說清楚。阿拉伯文、波斯文這類由右到左的書寫方向，對應的議題從 2021 年 12 月開立，到 2026 年 10 月中仍然開著，圖的生長方向也還是固定由左到右。匯出成 FreeMind 的 .mm 格式這個老需求，從 2022 年 5 月開立至今仍未實作；.mm 是老牌心智圖軟體 FreeMind 的通用格式，打不通這條路，代表想把手上的圖搬去別套工具的人得多繞一步。2026 年 3 月還有回報指出公式裡的中文字渲染不完整，數學筆記多的使用者要留意。加上前面說的引言丟失，以及預設輸出對 CDN 的依賴（開檔時瀏覽器會連向 jsdelivr，介意連線紀錄的人要改用 --offline），這幾條就是現階段的邊界清單。

從筆記出發的人有賺，從畫布出發的人不必換

判斷很簡單：你的內容活在哪裡。如果你已經用 Markdown 寫筆記，不管是放在 NoteGen 這類筆記應用裡，還是用現代 Markdown 編輯器寫文件，markmap 等於免費多送你一雙看結構的眼睛，一行指令的成本換一張可分享的互動圖，怎麼算都值得。最典型的場景是複習與簡報：讀書大綱轉成圖，收合到第二層先回憶，展開對答案；開會記錄轉成圖，寄給與會者比一堵文字牆友善得多。反過來，如果你要的是拖曳微調每個節點的位置、插入圖片做美編、或從零開始發散思考，畫布式工具仍然是正解，這兩種工具其實在回答不同的問題。

開始用的入口有幾個。完全免安裝的路徑是官方的 REPL 網頁，左邊貼 Markdown，右邊立刻出圖，頁面上還能調整展開層數、篩選節點、換單色模式，並提供下載互動 HTML 與下載 SVG 兩個按鈕，下圖就是它的介面。要提醒的是 REPL 是跑在別人伺服器上的服務，筆記內容會貼進那個頁面，介意的人走命令列，轉換全程在本機完成，什麼都不外送。命令列就是前面那行 npx 指令；已經在用 VSCode 的人，裝官方擴充功能就能在編輯器裡直接把 .md 檔預覽成心智圖。拿一則三層的讀書大綱試試，你會最快感覺到「樹本來就在」是什麼意思。

Pin