Obsidian 搭配 Hugo：個人知識庫與部落格寫作發布實戰指南

Obsidian 是一款強大的個人知識管理（PKM）與雙鏈筆記軟體，而 Hugo 則是極速的靜態網站生成器。將兩者結合，能讓你直接在 Obsidian 舒適的編輯器中撰寫草稿，完成後輕鬆發布至個人部落格！

本文將一步步帶你了解如何設定 Obsidian 搭配 Hugo，並妥善管理圖片與背景音樂等靜態資源路徑。

1. Obsidian 與 Hugo 搭配核心概念

#

Hugo 預設從 content/ 目錄讀取文章，而 static 靜態檔案（圖片、音樂、影片）則存放在 static/ 或文章同級的 Page Bundles 中。

為了確保在 Obsidian 預覽時能正確顯示圖片與播放音樂，且發布到 Hugo 後路徑不失效，建議採用以下兩種路徑管理模式之一：

模式 A：Page Bundles（頁面包裹模式，最推薦 👍）

#

將每篇文章建立獨立資料夾：

content/posts/my-cool-article/
├── index.md        <-- 文章內容
├── header.jpg      <-- 文章封面/圖片
└── bg-music.mp3    <-- 背景音樂

在文章中直接使用相對路徑引用：

![圖片描述](header.jpg)

模式 B：全局靜態資源（Global Static Folder）

#

將資源統一存放在 Hugo 的 static/ 資料夾中：

static/
├── images/
│   └── 2026/
│       └── photo.jpg
└── media/
    └── bg-music.mp3

在文章中統一使用全域絕對路徑 / 引用（Hugo 生成時會自動去掉 static 前綴）：

![照片](/images/2026/photo.jpg)

2. Obsidian 關鍵設定步驟

#

為了讓 Obsidian 生成的連結格式相容於 Hugo，請在 Obsidian 中進行以下設定：

1. 關閉 WikiLinks 格式：

   • 前往 Settings (設定) -> Files and links (檔案與連結)。
   • 關閉 Use [[Wikilinks]] 選項（確保 Obsidian 自動插入標準 Markdown 格式 [Text](link.md)）。

2. 設定附件存放目錄 (Attachment Folder)：

   • 於 Files and links -> Default location for new attachments 中：
     • 若採用 Page Bundles 模式：選擇 In the subfolder specified below 並設定為 ./ 或與文章同目錄。
     • 若採用 全局靜態資源 模式：選擇 In the folder specified below 並指向 Hugo 的 static/images 資料夾。

3. 連點相對路徑 (New Link Format)：

   • 選擇 Relative path to file（相對於檔案的相對路徑）。

3. 圖片與背景音樂（多媒體）路徑管理實戰

#

🖼 圖片管理

#

在 Obsidian 插入圖片時，語法如下：

<!-- 標準 Markdown 圖片語法 -->
![Obsidian 搭配 Hugo 架構圖](/images/obsidian-hugo-arch.png)

<!-- 若需調整圖片尺寸或樣式 (HTML 標籤) -->
<img src="/images/obsidian-hugo-arch.png" alt="架構圖" width="80%" style="border-radius: 8px;" />

🎵 背景音樂與音訊檔管理

#

若想在特定文章中加入背景音樂或語音旁白，可將 .mp3 或 .ogg 檔案放入 static/media/ 或文章同級目錄下。

方法 1：標準 HTML5 Audio 標籤

#

直接在 Markdown 文章中嵌入以下代碼：

<div class="audio-player" style="margin: 20px 0;">
  <p>🎧 <strong>背景音樂試聽：</strong></p>
  <audio controls preload="metadata" style="width: 100%;">
    <source src="/media/bg-music.mp3" type="audio/mpeg">
    您的瀏覽器不支援 HTML5 音訊播放。
  </audio>
</div>

方法 2：使用 Hugo Shortcode (可自訂美化)

#

在 Hugo 專案中的 layouts/shortcodes/audio.html 建立自訂元件：

<!-- layouts/shortcodes/audio.html -->
<figure class="custom-audio">
    <audio controls src="{{ .Get "src" }}"></audio>
    {{ with .Get "caption" }}<figcaption>{{ . }}</figcaption>{{ end }}
</figure>

在 Obsidian 撰寫 Markdown 時，只需調用 Shortcode：

4. Obsidian Front Matter 範本

#

可以在 Obsidian 中安裝 Templater 插件，點擊快捷鍵自動產生符合 Hugo 規格的 Front Matter 頁首：

---
title: '{{title}}'
date: {{date}}T{{time}}:00+08:00
draft: true
summary: ''
categories: ['技術']
tags: ['Obsidian', 'Hugo']
showToc: true
---

5. 發布自動化工作流總結

#

完成了上述設定後，未來的寫作與發布工作流程將變得極度簡潔：

graph LR
    A[Obsidian 撰寫筆記與插入圖片/音樂] --> B[檢查 Front Matter draft: false]
    B --> C[Git Commit & Push 到 GitHub]
    C --> D[GitHub Actions 自動編譯與發布]

1. 在 Obsidian 中無壓力撰寫草稿、加入圖片與背景音樂音訊。
2. 將 draft: true 改為 draft: false。
3. 送出 git push 指令，Hugo 與 GitHub Actions 將在 1 分鐘內自動完成全網站更新！