# 內容撰寫

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

## Content 結構

content 資料夾結構如下：

```sh
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        # 標籤頁
```

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

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

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

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

## Front Matter

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

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

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

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

```markdown {title="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](https://commonmark.org/) 規範解析 Markdown，如果不熟悉 Markdown 語法，可以參考 [Learn Markdown in Y minutes](https://learnxinyminutes.com/zh-cn/markdown/)，或在 [Playground](https://spec.commonmark.org/dingus/) 即時測試語法渲染結果。

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

```yaml
markup:
  goldmark:
    renderer:
      unsafe: true
```

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

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

```markdown
<div>

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

</div>
```

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

## 圖片引用{#referencing-images}

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

- `assets/`

  圖片放在 `assets/img/`，透過 Hugo Pipes 處理後引用：

  ```markdown
  ![說明文字](/img/photo.png)
  ```

- `頁面資源`

  圖片與內容檔案都放在 `content` 資料夾中的同一個目錄，以用相對路徑直接引用：

  ```markdown
  ![說明文字](foo.png)
  ```

- `static/`

  圖片放在 `static/foo.png`，會被原封不動複製到輸出目錄，需要用絕對路徑引用：

  ```markdown
  ![說明文字](/foo.png)
  ```

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

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

> [!INFO]
> 若圖片路徑解析失敗，則代表主題的 [image render hook](https://gohugo.io/render-hooks/images/) 邏輯錯誤，應回報給主題，或是自行啟用 `renderHooks.image.useEmbedded = always`。

## 文章引用

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

> [!INFO]
> 若連結路徑解析失敗，則代表主題的 [link render hook](https://gohugo.io/render-hooks/links/) 邏輯錯誤，應回報給主題，或是自行啟用 `renderHooks.link.useEmbedded = always`。

## Shortcodes

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

例如插入 YouTube 影片：

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

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

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

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

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




## Ancestors of This Page (Auto Generated)



- https://hugo-community-docs.github.io/zh-tw/docs/guide/index.md

- https://hugo-community-docs.github.io/zh-tw/docs/index.md