Obsidian to Astro - 自動生成 blog

前言

這篇文章記錄了我如何將 Obsidian 筆記系統與 Astro 靜態網站生成器整合。主要目的是讓我在 Obsidian 寫的筆記可以直接發布到網站上，不需要手動複製貼上或做額外的格式轉換。

整體流程概念圖

為什麼選擇分離式架構

一開始我考慮過把 Obsidian vault 直接放在 Astro 專案裡面，但後來發現這樣會有幾個問題：

首先是 Git 版本控制會變得很混亂。Obsidian 的日常筆記會產生大量 commit，如果跟網站開發的 commit 混在一起，根本沒辦法好好管理。

再來是安全性的考量。我的 Obsidian vault 裡面有很多私人筆記、工作筆記，萬一不小心整個推到公開的 repository，那就糟糕了。

最後是職責分離的問題。Obsidian vault 應該專注在內容管理，Astro 專案則專注在網站開發。把兩個不同性質的東西混在一起，長期來看只會增加維護成本。

所以最後決定採用分離式架構，用 rsync 腳本來處理同步。

資料夾結構

在 Obsidian vault 根目錄需要建立三個資料夾：

Images 存放所有筆記用到的圖片。每篇筆記都有自己的子資料夾，資料夾名稱要跟筆記標題一致。

Permanent Notes 存放要發布到網站的筆記。不是所有筆記都要發布，只有放在這個資料夾的才會同步到 Astro。

Templates 存放筆記模板。模板會幫我們自動產生 Astro 需要的 frontmatter 格式。

模板設定

在 Templates 資料夾裡面建立一個 Permanent Note Template.md：

---
title: "{{title}}"
description: ""
date: "{{date}}"
tags: []
---

# {{title}}

#### References

Tags : #

Obsidian 會自動把 {{title}}、{{date}} 替換成實際的值。我們只需要手動填寫 description 和 tags 就好。

注意：heroImage 已經改為選填，如果不需要封面圖可以不用設定。

圖片路徑規則

這個是整個流程最容易出錯的地方。路徑格式必須同時符合 Obsidian 和 Astro 的要求。

內文的圖片引用要用絕對路徑：

![示意圖](/Images/My_Post/screenshot.png)

開頭的 /Images/ 是關鍵。圖片會同步到 Astro 的 public/Images/ 資料夾，使用絕對路徑可以正確解析。

注意事項：

• 資料夾和檔案名稱不要有空格，用底線取代
• 避免使用特殊字元像是 &、\ 之類的
• Astro 的圖片最佳化套件會自動處理圖片，但路徑不能有特殊字元

同步腳本設定

由於 CI/CD 環境無法使用符號連結，我們改用 rsync 腳本來同步內容。

在 Astro 專案根目錄建立 sync-content.sh：

#!/bin/bash

# 設定來源和目標路徑
VAULT_PATH="$HOME/SynologyDrive/Ultimate Starter Vault"
PROJECT_PATH="$HOME/Desktop/Obsidian-to-Astro"

IMAGES_SOURCE="$VAULT_PATH/Images"
IMAGES_DEST="$PROJECT_PATH/public/Images"

POSTS_SOURCE="$VAULT_PATH/Permanent Notes"
POSTS_DEST="$PROJECT_PATH/src/content/blogPost"

# 同步圖片
echo "同步圖片..."
rsync -av --delete \
    --exclude='.DS_Store' \
    --exclude='*.tmp' \
    "$IMAGES_SOURCE/" "$IMAGES_DEST/"

# 同步筆記
echo "同步筆記..."
rsync -av --delete \
    --exclude='.DS_Store' \
    --exclude='*.tmp' \
    "$POSTS_SOURCE/" "$POSTS_DEST/"

echo "同步完成！"

給予執行權限：

chmod +x sync-content.sh

使用時直接執行：

./sync-content.sh

本地開發流程

完成設定之後，日常使用的流程是這樣：

步驟 1：建立新筆記

在 Obsidian 的 Permanent Notes 資料夾建立新筆記，使用 Permanent Note Template 模板。

步驟 2：建立圖片資料夾（如需要）

如果文章需要圖片，在 Images 資料夾建立對應的子資料夾。資料夾名稱要跟筆記標題一致，記得用底線取代空格。

例如筆記叫 My First Post.md，就建立 Images/My_First_Post/ 資料夾。

步驟 3：補充 frontmatter

填寫 description 和 tags。

步驟 4：撰寫內容

在 Obsidian 正常編輯就可以。圖片引用記得用正確的相對路徑格式。

步驟 5：同步內容到 Astro

cd ~/Desktop/Obsidian-to-Astro
./sync-content.sh

步驟 6：預覽效果

npm run dev

打開瀏覽器前往 localhost:4321，就可以看到剛才在 Obsidian 寫的筆記了。

步驟 7：發布到網站

確認內容沒問題之後：

git add .
git commit -m "新增文章：[文章標題]"
git push

如果是用 Vercel 部署，推送之後網站會自動更新。

實際範例

假設我要寫一篇關於量化交易的筆記：

1. 在 Permanent Notes 建立 Quantitative_Trading_Strategy.md
2. 使用模板並補充 frontmatter：

---
title: "Quantitative Trading Strategy"
description: "記錄我在量化交易上的一些策略思考和回測結果"
date: "2025-10-04"
tags: ["trading", "quantitative", "fintech"]
---

3. 撰寫內容，需要圖片時建立 Images/Quantitative_Trading_Strategy/ 並用相對路徑引用
4. 執行 ./sync-content.sh 同步到 Astro 專案
5. 執行 npm run dev 預覽效果
6. 確認無誤後 commit 並 push 到 GitHub

注意事項

關於檔名

檔案名稱和資料夾名稱都要避免空格。雖然作業系統支援，但在不同環境下可能會有問題。統一用底線或連字號比較保險。

關於版本控制

Obsidian vault 和 Astro 專案要用不同的 Git repository 管理。這樣可以分開備份，也不會把私人筆記誤傳到公開 repo。

關於圖片格式

Astro 3.0 內建圖片最佳化功能，會自動把圖片轉成 WebP 格式並壓縮。但前提是路徑不能有特殊字元，否則處理會失敗。

關於路徑一致性

所有圖片引用都要用 /Images/ 開頭的絕對路徑。圖片會同步到 Astro 的 public/Images/ 資料夾，Astro 會自動將 public/ 資料夾的內容提供為靜態資源。

為什麼用 rsync 而不是符號連結？

一開始我使用符號連結（symbolic link）來同步內容，在本地開發確實很方便。但部署到 Vercel 時發現 CI/CD 環境無法正確處理符號連結，導致 build 失敗。

改用 rsync 腳本後，有以下優點：

• 在任何環境都能正常運作，包括 CI/CD
• 可以排除不需要的檔案（如 .DS_Store）
• 同步時會自動刪除 Astro 專案中已經不存在於 Obsidian 的檔案
• 執行速度快，只更新有變動的檔案

唯一的缺點是需要手動執行腳本，不像符號連結會即時同步。但這也確保了更明確的內容控制。

總結

這套流程讓我可以專注在 Obsidian 寫筆記，不用擔心發布到網站的問題。透過簡單的 rsync 腳本，就能將筆記同步到 Astro 專案並發布。

整個流程的關鍵：

1. 分離架構 - Obsidian vault 和 Astro 專案完全分開
2. rsync 同步 - 可靠且支援各種環境
3. 路徑規範 - 統一使用相對路徑確保相容性
4. 簡化模板 - heroImage 改為選填，降低使用門檻

如果你也想把 Obsidian 筆記發布成網站，可以參考這個方法。維護成本低，運作穩定，適合長期使用。