我把 Heptabase 搬到 Obsidian，連白板、卡片和圖片一起留下來
我想把一門課從 Heptabase 搬到 Obsidian，真正麻煩的地方很快就出現了，文字可以匯出，但白板上整理好的位置、區塊、連線，以及卡片裡的圖片，不會因為有一包 Markdown 就自動變成另一套軟體裡的完整教材。
對我來說，白板的排法也是內容的一部分，哪幾張卡放在一起，章節怎麼分，從哪張卡連到下一張，都是整理過程留下來的脈絡，只搬文字，等於還要重新做一次整理。
所以我做了 Heptabase 搬家到 Obsidian，一套用完整備份產生 Markdown 筆記與 HTML 白板的開源工具，讓內容搬進 Obsidian，也讓沒有安裝 Obsidian 的人可以用瀏覽器閱讀。
先講最重要的界線：HTML 保留搬家當下的白板快照，Markdown 是之後要維護的正本，兩者不會自動同步，它也不是把所有 Heptabase 功能原封不動複製成 Obsidian 外掛。
我為什麼需要把 Heptabase 的課程搬出來
這套工具的起點是《我獨自升級！用 ChatGPT 打造一人公司》，課程在 Heptabase 裡有一張總覽白板與三張章節白板，共 72 張卡片，整個工作區則有 19 張白板、181 張卡片與 371 個圖片及附件，課程和其他資料必須分開計算，不能把全庫數量當成課程規模。
我在這次課程搬家的紀錄裡，把目標分成兩件事，一件是讓 Markdown 回到 Obsidian，由我和 AI 繼續整理，另一件是讓學生拿到資料夾後，不用先學一套新軟體，雙擊 HTML 就能看教材。
這兩種人需要不同的入口，自己維護內容時，我需要檔案、連結與可編輯的筆記，學生閱讀時，需要先看見全貌，再點進一張卡片，把兩個需求硬塞進同一個匯出格式，最後很容易兩邊都不好用。
Heptabase 可以匯出 Markdown，為什麼還要做搬家工具
Heptabase 官方的資料匯出說明本來就提供 Settings → Backup → Export now，也提醒接收資料的軟體不一定能保留白板排版、關係與中繼資料，這是跨工具搬家必須面對的差異。
如果你只需要幾篇卡片內文，官方匯出的 Markdown 可能就夠了，但我的課程大量依賴白板結構，所以工具會讀完整備份裡的 All-Data.json，取出卡片內容、白板物件、座標、區塊與連線，再把圖片和附件接回去。
白板的視覺排版交給 HTML，Obsidian 裡則保留每張白板的整理頁，依區塊與位置列出內容，也把連線整理成筆記之間的關係，這樣不用要求 Markdown 變成畫布，也不用為了重建每張白板而一直調整 Obsidian Canvas（畫布）。
搬到 Obsidian 之後，資料會變成什麼
搬家結果是一個新資料夾，最外層有 0-開啟白板.html 與 0-總覽.md，前者供瀏覽器查看，後者是 Obsidian 的入口頁，圖片與附件集中在 assets，另外保留搬家報告。
| 原本的內容 | 搬家後的位置 | 要注意的差異 |
|---|---|---|
| 白板與子白板 | 白板資料夾、整理頁與 HTML 白板 | 原本的視覺位置在 HTML 查看，Obsidian 整理頁以閱讀順序呈現 |
| 一般卡片 | 每張卡片一份 Markdown | 同一張卡出現在多張白板時只存一份，其他白板用連結引用 |
| 標籤與屬性 | 筆記的 tags 與 frontmatter（檔頭屬性） | 搬完仍需確認自己使用的欄位與內容格式 |
| 圖片與附件 | 共用的 assets 資料夾 | 備份沒包含的檔案會列為缺檔，不會被自動補回 |
| 未放上白板的卡片 | 專門的卡片資料夾與清單 | 全庫搬家時不會只搬畫面上看得到的卡片 |
卡片間的連結轉成 Obsidian 的 [[卡片名稱]]，輸出筆記的名稱會處理重複與特殊符號，例如兩張同名的「會議記錄」不會互相覆蓋，檔名有調整時，搬家報告也會記下來。
這裡最重要的是對帳，卡片有沒有落到輸出，圖片找不找得到，連結有沒有指向不存在的筆記，都要能重新檢查，資料夾存在只代表程式產生了東西，還不能代表可以放心取代原本的工作資料。
不想安裝任何東西，可以先看離線白板
如果你現在只想知道備份裡有什麼，先用Heptabase 離線白板檢視器就好，在 GitHub 檔案頁下載原始 HTML，用 Chrome、Edge 或 Arc 開啟，再把備份 ZIP 拖進去，不需要 Python，也不用安裝 Obsidian。
它可以瀏覽白板、點卡片讀全文、搜尋與查看轉換報告，這一步的用途是先確認輸入資料夠不夠完整，尤其是圖片有沒有真的包含在備份裡。
這裡的免安裝只指瀏覽器預覽，真正轉出 Obsidian 資料夾仍需要 Python 3.8 以上，HTML 檢視器目前以 Chromium 核心瀏覽器的使用經驗為基礎，Safari 與 Firefox 尚未完成同等驗證，不應直接當成全面支援。
真正搬進 Obsidian，我建議先跑一次示範資料
先匯出包含附件的完整備份
到 Heptabase 的 Settings → Backup，在 Export & Manual Backup 下選 Export Now，如果匯出畫面有 Include files and images，就確認已勾選，保留原始 ZIP，不必先把它解壓縮。
Heptabase 的備份說明指出，自動雲端備份不包含附件，所以不要把「已經有備份」直接理解成「圖片一定都在」，先用檢視器看轉換報告，比只看檔案大小可靠。
下載工具，再用虛構資料練一次
從專案 GitHub 頁面選 Code → Download ZIP，把工具解壓縮，注意這裡解壓的是工具專案，Heptabase 備份 ZIP 仍然可以直接交給程式讀取。
在終端機切換到解壓後的專案資料夾，先確認 python3 --version，Windows 可用 python --version，沒有 Python 時可從 Python 官方網站安裝，Windows 安裝時要讓 Python 加入 PATH（指令搜尋路徑）。
Mac 的示範指令是 python3 scripts/migrate.py examples/demo-backup.zip "示範搬家結果"，Windows 的 PowerShell 則是 python scripts\migrate.py examples\demo-backup.zip "示範搬家結果"，示範備份是虛構內容，裡面刻意放了同名卡片、特殊符號、子白板和缺圖等狀況。
用這份示範備份跑一輪，白板是 3／3 張，卡片是 12／12 張，實際輸出 4 個圖片與附件，報告另外指出原始備份缺少 1 個檔案，連結與檔名檢查通過，這代表已知缺檔被清楚列出，不代表缺少的圖片已經被找回。
再換成自己的備份，輸出到新資料夾
把備份 ZIP 複製到專案資料夾，下方以 Heptabase-Data-Backup.zip 當示意檔名，實際操作時換成你下載的名稱，輸出資料夾也選一個還沒使用過的名稱。
Mac：python3 scripts/migrate.py "Heptabase-Data-Backup.zip" "Heptabase搬家結果"。
Windows PowerShell：python scripts\migrate.py "Heptabase-Data-Backup.zip" "Heptabase搬家結果"。
只搬部分內容，可以在指令後加 --board "白板關鍵字"，它會包含符合名稱的白板與子白板，要排除特定白板則用 --exclude-board "白板關鍵字"，兩種選項都可以重複使用，HTML 改成淺色可加 --theme light。
完成後先看 _搬家紀錄/搬家報告.md 與 _搬家紀錄/白板轉換報告.md，確認卡片數、白板數、缺檔、改名與未支援項目，再雙擊 0-開啟白板.html 對照幾張重要卡片。
驗收後才放進正式 Vault
工具會在搬家流程裡檢查連結、圖片與檔名，需要再次檢查時，Mac 可執行 python3 scripts/verify.py "Heptabase搬家結果"，Windows 則把 python3 換成 python，路徑改用 scripts\verify.py。
確認結果後，可以把整個輸出資料夾放進既有 Vault（筆記庫），或依 Obsidian 開啟既有資料夾的方式選 Open folder as vault，從 0-總覽.md 開始閱讀，移動資料時要連同 assets 一起保留。
程式遇到非空的輸出資料夾會停止，這個保護是讓你重新搬家時先產生另一份結果，再決定怎麼合併，避免把已經在 Obsidian 裡改過的筆記蓋掉。
哪些內容會留下，哪些現在還不能搬
這個專案的踩坑清單涵蓋圖片同名、Mac 與 Windows 檔名編碼、特殊符號、重複標題、子白板與舊平台連結等情境，但它不等於所有資料格式都已經支援。
日誌 Journal、PDF 卡、Highlight（標註）、AI Insight 與心智圖目前不會轉成完整可用的 Obsidian 筆記，搬家報告會列出相關數量，原始內容仍需保留在備份裡，若這些是你的主要資料，先確認限制再決定是否使用。
文字顏色、底線與部分排版會用 HTML 標籤保留，Obsidian 的閱讀模式可以呈現，但其他 Markdown 編輯器未必有同樣效果，白板排版也不是 Obsidian Canvas 的一比一複製。
目前工具依 Heptabase 1.112 的備份資料結構開發，未來匯出格式若改變，不能保證直接相容，遇到問題時先保留備份，查看報告後再回報，報告可能包含卡片標題與檔名，公開貼到 Issue 前要先檢查內容。
另一個差異是網路，Python 轉換與本機 HTML 不會把備份上傳到服務，但卡片原本就含外部圖片或 YouTube 影片時，瀏覽器仍可能向原網址請求內容，本機處理不等於所有外部素材都能離線播放。
如果把備份交給 Claude Code 或其他 AI 代理協助，還要另外考慮該 AI 的資料處理方式，工具本身不上傳，不代表整段 AI 協作也一定完全留在本機。
搬家之後，教材要有讀者看得懂的入口
我在課程案例裡又往前做了一步，把 Markdown 整理成可閱讀的教材包，最外層只留明確的 HTML 與 Markdown 入口，讓學生雙擊 HTML 就能看全覽、搜尋與點開教材。
這個進階閱讀器與一般搬家白板不同，它會把 Markdown 打包進閱讀器，也提供「讀取最新 MD」入口，但打包程式依賴課程自己的 frontmatter 結構，不能把它當成所有資料都能直接套用的通用功能，實作在課程教材包範例。
我做這套工具，是希望原本整理過的內容搬到新地方之後仍然可讀、可改，也能知道少了什麼，對已經用 Heptabase 整理課程、研究或知識白板的人，先預覽、對帳，再決定要不要搬，比直接把匯出檔塞進正式 Vault 更穩妥。
程式採 MIT License（MIT 授權），可以使用、修改與分享，使用程式不需要 AI API Key，若你想讓 Claude Code 帶著操作，專案也附了 SKILL.md，但這是選用流程，一般搬家不必先安裝 AI 工具。
推薦閱讀
- Obsidian 是什麼？一篇搞懂這款筆記軟體為什麼讓工程師和研究者都瘋狂
- Obsidian 教學：新手下載、入門設定、必裝外掛一次看懂
- Hans Kanban：把筆記變好閱讀的 Obsidian 看板預覽
參考資料
- Heptabase 搬家到 Obsidian：原始碼與使用說明
- 專案踩坑清單：匯出、圖片、檔名與排版
- 課程搬家與教材包案例
- Heptabase 官方：資料匯出與可攜性
- Heptabase 官方：自動備份與完整附件備份
- Obsidian 官方：把既有資料夾開成 Vault
常見問題 FAQ
Heptabase 搬家到 Obsidian 是 Obsidian 外掛嗎？
不是，它是一套備份轉換程式與 HTML 檢視器，預覽白板只要瀏覽器，產生 Obsidian 資料夾需要 Python 3.8 以上，不需要先安裝外掛，也不需要 AI API Key，程式採 MIT 授權。
Heptabase 的所有資料都能完整搬到 Obsidian 嗎？
不能保證所有類型都搬過來，一般卡片、白板結構、標籤、屬性與備份內可找到的圖片是主要處理範圍，Journal、PDF 卡、Highlight、AI Insight 與心智圖有已知限制，HTML 保留白板快照，Obsidian 的白板整理頁不是一比一畫布。
使用搬家工具，備份會上傳到網路嗎？
工具的 Python 轉換與本機 HTML 檢視器不會上傳備份，但原卡片內的外部圖片或 YouTube 影片可能向原網址載入，若另外使用雲端 AI 代理讀取備份，仍要依該 AI 的資料處理方式評估，不能把工具的本機處理擴大成整段流程都不出網路。
在 Obsidian 改完筆記，HTML 白板與 Heptabase 會同步嗎？
不會，一般 HTML 白板是搬家時的快照，原本的 Heptabase 也不會跟著更新，搬完之後以 Markdown 為正本，需要新快照時重新匯出到新的資料夾，進階課程閱讀器則提供重新打包或讀取最新 Markdown 的不同流程。
搬家會覆蓋原本的 Vault，或把缺少的圖片補回來嗎？
不會覆蓋既有 Vault，也不會自動找回備份裡沒有的圖片，程式要求新建或空的輸出資料夾，非空就停止，缺檔會寫進報告，確認報告與重要卡片後，再由你決定是否把結果放進正式 Vault。
