阿若（Michelle）

官方文件教學

目錄可以讓讀者快速瀏覽文章架構，並找到所需資訊，還能優化 SEO、提升使用者體驗

本文將介紹如何使用 Hugo 內建的變數來生成目錄，並自定義所需內容，提升文章的結構性與可讀性，優化閱讀體驗

一、啟用 Hugo 內建目錄功能

Hugo 提供內建的變數來自動生成目錄

只要在文章範本加上 {{ .TableOfContents }} 變數即可啟用

每個 Hugo 主題的文章範本可能位於不一樣的地方

以這個部落格為例，我們使用的主題是 Liva-Hugo，文章範本位於 layouts/_default/single.html

參考程式碼如下：

<aside class="toc">
  <h2>目錄</h2>
  {{ .TableOfContents }}
</aside>

二、設定目錄的標題層級與格式

Hugo 目錄預設會從 h2 開始，顯示到 h3

若想更改顯示的標題層級，可於 Hugo 的 config.toml 中調整

像是這邊習慣以 h3 當作內文的主標題，h4 當副標題，因此程式碼會呈現如下：

[markup]
  [markup.tableOfContents]
    startLevel = 3 // 從 h3 標題開始列入目錄
    endLevel = 4 // 列到 h4 為止
    ordered = true //是否使用有序列表

圖 2 目錄之標題層

三、在文章中使用標題層級

Hugo 的目錄會自動根據 Markdown 的標題層級生成

### h3 標題（主標題）
#### h4 標題（副標題）

圖 3 Markdown 的標題層級

四、自訂樣式

以下為此部落格使用之目錄樣式

aside.toc {
  background-color: #FFFFFB;
  border: 2px solid #f7bf57;
  border-radius: 5px;
  padding: 1rem;

  ul li {
    &::before {
      content: "";  /* 移除 Hugo 主題可能自帶的 icon 或數字符號*/
    }

    a {
      display: block;
      line-height: 2;
      color: #434243;
    }
  }
}

圖 4 目錄樣式

五、針對特定文章啟用 / 停用目錄功能

若是有些文章段落較短，或偏隨筆日誌，不太需要目錄功能的話，可以在文章中的 Front Matter 中進行設定

Front Matter 是在 Markdown 文件開頭的設定區塊，在 Hugo 架站步驟這篇文章中，我們提到文章開頭需要撰寫以下設定：

---
title: "標題"
date: 日期（2024-04-28）
draft: 是否為草搞（true/false）

image: "圖片網址"
---

這個區塊就是 Front Matter

而我們可以在這個區塊加上 toc 參數，來決定是否要啟用目錄功能

但若是使用的部落格主題沒有支援 toc 參數，則需要自行修改模板

Liva Hugo 沒有此參數，故我們要先新增目錄參數才能使用它

在前面段落提到的啟用目錄功能中，將程式碼增加 if 判斷是否要啟用或停用目錄：

{{ if .Params.toc }}
<aside class="toc">
    <h2 class="text-center">目錄</h2>
    {{ .TableOfContents }}
</aside>
{{ end }}

之後就可以在 Front Matter 設定

toc: true / false

六、結語

會使用到這個功能主要是因為在整理網站作品集時發現文章內容好長

如果沒有目錄，會降低我的閱讀意願

在實作過程中，沒有遇到太大的問題，若大家有其它心得，歡迎分享～

在 Hugo 中實作文章目錄功能