內容撰寫 | Hugo 社群文檔

本篇說明撰寫文章內容會用到的相關知識，包含 content 目錄結構，Markdown、front matter 與 shortcode。

Content 結構

content 資料夾結構如下：

content
├── _index.md            # 1. 主頁
├── docs
│   ├── _index.md        # 2. 列表頁
│   ├── p1.md            # 3-1. 文章頁面：直接使用檔名
│   ├── p2               # 3-2. 文章頁面：使用 index.md
│   │   ├── cover.jpg
│   │   └── index.md
│   └── bar              # 深層列表頁
│       ├── _index.md    # 深層頁面的列表頁
│       ├── post-1.md
│       └── post-2.md
└── tags
    ├── _index.md        # 4. 標籤頁面的列表頁
    └── my-tag.md        # 標籤頁

主頁是放在最上層的 _index.md
其餘帶有底線的 _index.md 都是列表頁
文章頁面可以使用檔名.md，也可以使用檔名/index.md，不會再有子頁面
標籤頁的 _index.md 同樣代表列表頁

p1.md 和 p2/index.md 都可以建立獨立的文章，但是只有 p2/index.md 形式可以擁有自身頁面的資源，如圖片或影片。您應該永遠選擇 post-name/index.md 形式這樣專案結構才會統一，除非兩種情況：

網站幾乎沒有圖片等資源
網站資源規劃全部放到 assets 目錄

這兩種情況都用不到頁面資源，因此直接使用 post.md 顯然更乾淨簡潔。

Front Matter

Front matter 是每個內容檔案開頭的區塊，記錄該篇內容的中繼資料，支援 yaml、YAML、JSON 三種格式，純粹以分隔符號區分：

yaml：+++ 包起來
YAML：--- 包起來
JSON：直接用 { } 包起來

三者沒有差異功能擇一使用即可，但建議使用 YAML，因為多數工具預設支援 YAML，甚至只支援 YAML。

一個 YAML 格式的 Markdown front matter 看起來會是這樣：

posts/article-1/index.md
---
title: '我的第一篇文章'
date: '2026-08-15T10:00:00+08:00'
lastmod: '2026-08-15T10:00:00+08:00'
draft: false
tags: ['hugo', '筆記']
params:
  showToc: true
---

這裡開始是文章正文。

常見欄位：

欄位	用途
`title`	標題
`date`	發布日期，若日期是未來則需要 `-F` 旗標才會構建該文章
`lastmod`	最後修改日期
`draft`	草稿狀態，若是 `true` 則需要 `-D` 旗標才會構建該文章
`tags` / `categories`	分類，依主題支援情況顯示
`weight`	手動排序權重
`params`	主題自訂設定，Hugo 核心不處理，完全交由主題模板讀取

frontmatter 的設定會覆蓋 hugo.yaml 的設定；params 則是主題自訂設定，雖然主題設定不放在 params 底下 Hugo 也能讀取，但是建議永遠加上，這樣在遷移主題、網站管理上會更直觀清晰。

Markdown

Hugo 遵循 CommonMark 規範解析 Markdown，如果不熟悉 Markdown 語法，可以參考 Learn Markdown in Y minutes，或在 Playground 即時測試語法渲染結果。

Markdown 內容中也能直接寫 HTML，但預設會被移除，需要在 hugo.yaml 開啟：

markup:
  goldmark:
    renderer:
      unsafe: true

未開啟時 HTML 標籤會被移除。

另外，HTML 與前後的 Markdown 內容之間必須有空行，否則 Goldmark 會將該區塊視為純 HTML，不會解析其中的 Markdown 語法：

<div>

這裡的 **粗體** 會被正確渲染。

</div>

<div>
這裡的 **粗體** 不會被渲染，會直接輸出星號。
</div>

圖片引用

圖片的存放位置決定了引用它的方式。 Hugo 中有三個常用的存放位置：assets/ 目錄、與內容檔案並列的頁面資源，以及 static/ 目錄。後續章節將詳細介紹完整的目錄結構；目前僅針對這三種位置引用圖像的方法做介紹：

assets/
圖片放在 assets/img/，透過 Hugo Pipes 處理後引用：
```
![說明文字](/img/photo.png)
```
頁面資源
圖片與內容檔案都放在 content 資料夾中的同一個目錄，以用相對路徑直接引用：
```
![說明文字](foo.png)
```
static/
圖片放在 static/foo.png，會被原封不動複製到輸出目錄，需要用絕對路徑引用：
```
![說明文字](/foo.png)
```

hugo-community-docs 建議將圖片應該放在 assets/：

static/ 的檔案不會經過任何處理，即使沒用到也會被輸出。
static/ 使用絕對路徑（/foo.png），網站部署到子目錄（例如 example.com/blog/）時，所有連結都要跟著調整；assets/ 透過 Hugo 產生的連結會自動對應正確路徑，網站搬遷或改變部署路徑時不需要手動修改任何連結。
頁面資源 目的是在自身頁面取用自身資源，其他頁面難以取用別的頁面的頁面資源。

資訊

若圖片路徑解析失敗，則代表主題的 image render hook 邏輯錯誤，應回報給主題，或是自行啟用 renderHooks.image.useEmbedded = always。

文章引用

hugo-community-docs 建議一律使用包含副檔名的方式連結，比如 [link](../post-1/index.md)，因為這樣 IDE 才能夠補全、跳轉以及檢查錯誤的連結。

資訊

若連結路徑解析失敗，則代表主題的 link render hook 邏輯錯誤，應回報給主題，或是自行啟用 renderHooks.link.useEmbedded = always。

Shortcodes

Shortcode 是在 Markdown 內容中插入模板邏輯的方式，用來處理 Markdown 語法做不到的事，例如插入影片、建立 tabs、呼叫主題提供的元件。

例如插入 YouTube 影片：

{{< youtube id="dQw4w9WgXcQ" >}}

Shortcode 有兩種語法：{{< >}} 與 {{% %}}。實務上約九成情況會用到 {{< >}}，但具體哪個 shortcode 該用哪種語法取決於該 shortcode 的原始碼實作方式，請以主題或該 shortcode 作者提供的文件為準。

如果要在內容中直接顯示 shortcode 語法本身而不執行它，需要用 {{</* */>}} 包起來：

{{</* youtube id="dQw4w9WgXcQ" */>}}