前言
上週考完 iPAS AI 應用規劃師（初級）後，我一直有個想法：把自己累積的 Obsidian 筆記公開上線。不然辛苦寫的筆記，只有自己看一次太浪費了！
這也可以說是一種整理自我知識的儀式感。筆記存在本機，只有自己看得到；但一旦部署成網站，你會不自覺地開始在乎架構、在乎品質。這對知識管理是一種很好的外部壓力。
抱著這個想法，我問 ChatGPT 一個問題：
我想要把 Obsidian 的筆記免費變成公開網站，可以透過哪些工具？要保留筆記之間的雙向連結，不需要再重新調整。
拿到 ChatGPT 給我的幾的選項後，我挑了看起來最直接的 Quartz。
但我不是工程師，Git 指令、Node.js、GitHub Actions — 這些對我來說都是模糊的「技術詞彙」。最後花了 2–3 小時，靠著Codex CLI引導，把整套 Obsidian + Quartz + GitHub Pages 流程走完了。這篇文章就是記錄這段過程，以及途中踩到的坑。
筆記網站連結：KPI 的 AI 應用規劃師筆記
你需要先準備什麼
- GitHub 帳號：用來放程式碼、部署網站，免費
- Git：電腦上的版本控制工具，需要安裝
- Node.js：Quartz 用來建置靜態網站的執行環境，需要安裝
- Obsidian：你應該已經有了，不然也不會想看這篇
- AI 助手：這次我主要用的是 Codex CLI，遇到問題也可以用 Gemini CLI 或 Claude Code 輔助
給非工程師的心理建設
網路上有些教學看起來很簡單，幾步就搞定。但那些作者大多已有 Git 基礎。如果你是第一次接觸，預估 2–3 小時是正常的。重點是 AI 助手能幫你渡過大部分卡關的時刻，保持耐心與好奇心！
整個流程長什麼樣子
簡單來說，整體步驟如下：
- 你寫好的 Obsidian 筆記
- 放進 Quartz 的 content 資料夾
- Push 到 GitHub
- GitHub Actions 自動建置
- GitHub Pages 公開你的網站
整體分工：
- Obsidian 負責讓你寫筆記內容
- Quartz 負責把 Markdown 轉成靜態網站
- GitHub Pages 負責把網站公開在網路上
步驟說明（Codex CLI 幫你做）
以上這些步驟我一開始也不懂，更別說細節要怎麼操作了！整個過程是這樣進行的：
首先，開啟一個專案資料夾，打開 Codex CLI，把你想做的事用白話說給它聽。
例如：
「我想用 Quartz 把我的 Obsidian 筆記部署到 GitHub Pages，請幫我一步一步完成，我是第一次用 Git。」
然後 Codex CLI 會給你指令、解釋每一步在做什麼，你照著執行，遇到 Bug再複製或截圖貼給它看。(Ps. 要截圖給 Codex CLI，就直接把截圖檔案存放在專案目錄下，請它讀取即可。)
幾個需要理解的概念：
- 在專案資料夾中，Codex CLI 會先把Quartz的檔案抓下來到本地(clone)。
- 讓 Quartz 知道你的筆記在哪（把要公開的筆記放進
content資料夾內） - 建一個 GitHub repo（去 GitHub 網站新增，網路上有很多教學，或問問 GPT）
- 告訴 GitHub 要自動部署（設定 GitHub Actions，這個 Codex 可以幫你處理）
- Push，等它跑完，網站就上線了(請Codex CLI幫你上傳到Github指定的repo中)
- 之後要更新筆記時，把新筆記放入
content資料夾，再次 Push 即可。
在 GitHub 專案 repo 裡面的 Action 頁面，可以找到 Deloy，每次筆記更新、Push 後，等幾分鐘，出現綠色勾勾代表網站更新完成。
途中踩到的坑
用 AI 來幫忙寫程式，一定會遇到各式各樣的阻礙，以下是我曾經遇到過的問題，記錄下來說不定可以幫到你。當然，電腦環境不同 + GenAI 的隨機性，會讓每個人踩到不同的坑，遇到了，就好好和 AI 聊聊吧！
坑 1：中文變成亂碼
現象：網站出現「人工?慧?本概念」這樣的亂碼字。剛看到整篇筆記都變成亂碼時小小驚嚇了一下！
原因：我請 Codex CLI 幫我修改 .md 檔，但 PowerShell 在 Windows 環境的預設編碼不是 UTF-8。工具讀取中文檔案時，用錯誤的編碼解析再寫回去，原本的中文字元就被替換成問號 ? 和方塊。
解法：從上一個正常的 Git commit 還原檔案，再重新加入設定。或直接把你手邊的備份檔案覆蓋上去。
重要！不要直接讓 AI 工具操作你的原始筆記檔案。
除非你很有把握，不然不要把珍貴的原始資料丟給生成式AI處理。
我的做法是：另外複製一個資料夾作為專案資料夾，讓AI 在那邊操作。萬一出問題，我辛苦寫的筆記完全不受影響，只要用正確的原始檔案覆蓋回去即可。
坑 2：點擊連結一直空轉
現象：點某幾篇筆記的連結，頁面一直 loading，無法正常顯示。
原因：我某些 Obsidian 筆記的 alias（別名）設定，和筆記名稱完全一樣。Quartz 在解析時，連結一直重新導向到自己，陷入無限迴圈。
解法：請Codex CLI查詢後找到問題，把那些相同的 alias 刪除或修改即可。
坑 3：部分連結失效
現象：網站上某些筆記連結點了沒有反應或出現 404 網頁不存在。
原因：Markdown 的連結語法是 [文字](位址.md)，括弧是語法的一部分。我有些筆記名稱用了全形和半形混用的括弧，例如：
決策樹（Decision Tree)注意到了嗎？前面是全形的 （，後面是半形的 )。這導致連結語法被截斷，讀取成不完整的路徑。
解法：把筆記名稱中的括弧全部統一改成全形。
幾個值得注意的事
關於 Obsidian 外掛語法
Quartz 主要處理標準 Markdown。如果你的筆記大量使用 Dataview 查詢或其他特定外掛語法，這些在網站上通常無法正確顯示。發佈前需要檢查一下。
關於圖片
圖片路徑要跟著筆記一起放進 content 資料夾，且路徑要正確對應，否則建置後圖片會找不到。
私密內容提醒
就算 GitHub repo 設為 Private，GitHub Pages 部署出去的網站仍然可能是公開可存取的。不要把私人或工作敏感筆記放進去。
結語
這一年來AI工具突飛猛進，讓很多人可以透過AI實現自己想要完成的事情。我以前曾有自學python的經驗，花了好幾個晚上處理一直跳出來的報錯bug，容易最後就放棄了。現在有 AI 陪你查錯、解釋原因、給出下一步，整個摸索過程變得可以承受。
AI 工具降低的不只是技術門檻，而是「試錯的心理成本」。
當然，中間還是有很多卡關的時刻。但只要你願意多花一點時間，用「每一步驟都確認一次」的原則推進，沒有資訊背景的你也完全可以走完這條路。
最後再次提醒：
- 不要讓 AI 直接操作原始檔案，永遠留一份乾淨的備份
- 每個小步驟就確認成果，不要一次改一堆再最後檢查
如果你也有 Obsidian 筆記，不妨試試看把它變成一個網站！
