佈景主題參數 (全站)

此處列出佈景主題內建的全站參數，控制層面為網站首頁、整體 UI，以及 SEO 等。

2025 年 10 月 4 日多語版本：

English

提示
主題本身可開箱即用，自帶合理預設值，你一開始可以完全不碰這些設定，等需要的時候再添加。

關於全站設定檔

此主題提供的全站參數都巢狀歸在 params.neso 命名空間下，也就是說，你在專案根目錄下的 hugo.toml 內應該像這樣寫：

[params]
  [params.neso]                  # 表頭
    support_theme_author = true  # 設定鍵、值
    [params.neso.home]
      display_mode = "profile"
      # 下略...

你也可以依照自己的需求，將設定擋拆分成多個檔案，詳見 Hugo 官方文件。

補充
Hugo 本身也接受 YAML 或 JSON 格式的設定檔，有需要的話，請自行尋找格式轉換工具。

頂層設定

表頭：[params.neso]。

鍵名	類型	說明
`time_format`	`String`	用於顯示文章發佈時間的格式，詳細文件
`disable_responsive_menu`	`Boolean`	停用響應式網站主選單
`show_breadcrumbs`	`Boolean`	在頁面上方顯示麵包屑導覽列 (可透過頁面的 Front Matter 單方面關閉)
`ext_link_indicator`	`Boolean`	為外連的超連結加上提示 icon
`ext_link_no_opener_referrer`	`Boolean`	為外連的超連結 `<a>` 元素加上 `noopener`、`noreferrer` 等 `rel` 屬性值
`ext_link_new_window`	`Boolean`	在新分頁/視窗打開外連的超連結
`show_full_content_in_rss`	`Boolean`	在 RSS 輸出內包含內容全文 (預設使用文章 Front Matter 的 `Summary`)
`archive_includes_all_sections`	`Boolean`	在 Archives 頁面納入所有 Section 的文章 (預設為 `false`：僅納入 `mainSections`)
`disable_scroll_to_top`	`Boolean`	隱藏並停用「回到頁面頂端」按鈕
`footer_text`	`String`	附加在網站頁尾版權聲明後的自訂字串
`hide_copyright`	`Boolean`	隱藏網站頁尾的版權聲明
`support_theme_author`	`Boolean`	在網站頁尾顯示 “Powered by” 字樣，鼓勵此佈景主題的作者 (謝謝 🥹)
`hide_footer`	`Boolean`	隱藏整個頁尾區塊 (版權、自訂文字、“Powered by” 字樣)
`force_color_scheme`	`false` `String`	設為 `false`時，在網站頁尾顯示色彩切換 UI 供讀者切換；若設為字串 `"system"` (跟隨使用者系統設定)、`"light"`、`"dark"` 則隱藏色彩切換 UI，並指定網站的色彩模式
`display_short_lang_name`	`Boolean`	若網站提供多語內容，頂部導航列顯示的語言名稱使用 “EN”、“ZH” 等縮寫，而非 “English”、“中文” 等語言全稱

品牌

表頭：[params.neso.branding]。

重要
以下設定涉及的圖檔眾多繁雜，但其實只要 og_image、favicon_ico、favicon_svg 基本三者就可取得良好的顯示和連結預覽效果，其餘圖檔用於確保在特定環境下的完美呈現，對多數人來說可忽略不設。

鍵名	類型	說明
`logo_text`	`String`	自訂頂部導航列 logo 字樣 (此字串僅於導航列用作 logo 顯示，其他需要用到站名的地方都是取全站設定的 `Title` 值)
`hide_logo_text`	`Boolean`	隱藏頂部導航列 logo 字樣
`logo_image`	`String`	設定頂部導航列的 logo 圖像 URL
`logo_image_dark`	`String`	設定頂部導航列的 Dark Mode 版 logo 圖像 URL (網站外觀處於深色模式下才會顯現)
`logo_image_width`	`Integer`	設定頂部導航列的 logo 圖像寬度 (單位為 `px`，填寫時勿帶單位)
`logo_image_height`	`Integer`	設定頂部導航列的 logo 圖像高度 (單位為 `px`，填寫時勿帶單位)
`og_image`	`String`	設定全站預設的 `og:image` 圖像 URL；建議尺寸為 1200×630 px
`favicon_ico`	`String`	設定網站的 favicon 圖像 URL (副檔名 `ICO`)；出於支援性、SEO 的考量，除非有特殊需求，否則強烈建議檔名使用 `favicon.ico`、直接放在 Hugo 專案根目錄下的 `static/` 頂層，並將此設定留空
`favicon_svg`	`String`	設定網站的 favicon 圖像 URL (副檔名 `SVG`)；SVG favicon 在現今環境已有良好支援，顯示效果較佳
`apple_touch_icon`	`String`	設定網站的 `apple-touch-icon` 圖像 URL (副檔名 `PNG`)
`pwa_short_title`	`String`	設定行動設備將網站加入主畫面時，所顯示的名稱 (可用較簡短的字詞來取得良好顯示效果)
`pwa_theme_color_light`	`String`	設定網站的 16 進位主題色碼 (如 `#bada55`)，支援的瀏覽器會將 UI 染色，以提供更沈浸的瀏覽體驗；建議以網站背景色為設定依據
`pwa_theme_color_dark`	`String`	設定網站的 16 進位主題色碼 (如 `#bada55`)，支援的瀏覽器會將 UI 染色，以提供更沈浸的瀏覽體驗；建議以網站背景色為設定依據，此設定專用於深色模式的瀏覽環境
`pwa_icon_svg`	`String`	設定網站的 PWA icon URL (副檔名 `SVG`)
`pwa_icon_192`	`String`	設定網站的 PWA icon URL (副檔名 `PNG`，尺寸 192×192 px)
`pwa_icon_512`	`String`	設定網站的 PWA icon URL (副檔名 `PNG`，尺寸 512×512 px)
`pwa_icon_maskable_svg`	`String`	設定網站的遮罩版 PWA icon URL (副檔名 `SVG`)
`pwa_icon_maskable_192`	`String`	設定網站的遮罩版 PWA icon URL (副檔名 `PNG`，尺寸 192×192 px)
`pwa_icon_maskable_512`	`String`	設定網站的遮罩版 PWA icon URL (副檔名 `PNG`，尺寸 512×512 px)

補充
帶有 pwa_ 前綴的設定，本佈景主題將依 W3C 規格，幫你打包生成 manifest.json 檔案，詳見 web.dev 與 MDN 說明。
關於 PWA icon 各種版本的適用情境和詳細製圖規格，可查閱 web.dev。

社交平台連結

表頭：[params.neso.social]。

此處的設定用來在網站首頁顯示你的社交平台連結，在 TOML 以「Array of Tables」形式編寫，範例如下：

[params]
  [params.neso]
    # 其他設定略...
    [params.neso.social]
      [[params.neso.social.links]]
        name = "Github"
        url  = "https://github.com/babeneso"
      [[params.neso.social.links]]
        name = "X"
        url  = "https://x.com/babeneso"
    [params.neso.home]
    # 其他設定略...

鍵名	類型	說明
`name`	`String`	平台名稱；大小寫無關緊要，但拼字務必正確 (英文)，以確保能顯示正確的 icon
`url`	`String`	你在該平台的個人頁面 URL

首頁

以下是首頁設定的詳細說明。

準備 Index 檔案

在 Hugo 專案根目錄下的 content/ 頂層建立一個 _index.md 檔案 (注意開頭底線)，在裡面編寫以下內容：

---
# 首頁用的 Front Matter 只需要以下這兩條：
title       : "奶獸喵喵之家"
description : "喜歡做菜、弄些小點心，夢想是每天抱著貓貓，睡到太陽曬屁股！"
---

# 主要內容區域，`display_mode` 設為 "profile" 以外的模式才會用到。
# 如果檔案是 "_index.md"，你可以在這裡寫 Markdown 語法充實內容；
# 如果檔案是 "_index.html"，你可以在這裡寫 HTML 語法，自行實現更複雜的內容。

選擇排版設計
在 hugo.toml 全站設定檔內的 [params.neso.home] 表頭下設定排版模式：
```
[params]
  [params.neso]
    # 其他設定略...
    [params.neso.home]
      display_mode = "profile"
    # 其他設定略...
```
display_mode = "profile"
顯示大頭照、標題、自介文字、以及社群連結和自訂連結按鈕，置中排版。此模式較簡潔，不會採用 Index 檔的主要內容。
display_mode = "intro"
顯示標題、社群連結、Index 檔的主要內容，依語系書寫方向排版。
display_mode = "<其他任何字串>"
高度自訂模式，僅顯示 Index 檔的主要內容。
在此模式下，推薦採用 _index.html 檔名，然後直接在裡面寫 HTML 原始碼——這些原始碼會被包在一個響應式寬度容器內，所以你不需要從頭寫 <html>、<body> 等標籤，直接寫內容就好。
佈景主題內已佈下 Tailwind CSS 處理管線，你可以搭配使用各種 utility class。

細部設定：`"profile"` 模式

子表頭：[params.neso.home.profile]。

鍵名	類型	說明
`avatar_image`	`String`	設定大頭貼圖像 URL
`avatar_image_alt_text`	`String`	設定大頭貼圖像的替代文字
`avatar_image_size`	`Integer`	設定大頭貼圖像的尺寸，一個正整數即可，大頭貼長寬相同 (單位為 `px`，填寫時勿帶單位)
`avatar_image_size_sm`	`Integer`	設定大頭貼圖像在行動裝置 (小螢幕) 的尺寸，一個正整數即可，大頭貼長寬相同 (單位為 `px`，填寫時勿帶單位)

你還可以額外設定一些連結按鈕，顯示在自介下方，在 TOML 以 Array of Tables 形式編寫，範例如下：

[params]
  [params.neso]
    # 其他設定略...
    [params.neso.home.profile]
      avatar_image = "img/profile-photo.jpg"
      # 其他設定略...
      [[params.neso.home.profile.link_btns]]
        label = "下載我的履歷"
        url   = "https://example.com/resume"
      [[params.neso.home.profile.link_btns]]
        label = "經手專案"
        url   = "https://github.com/babeneso"
    [params.neso.home.list]
    # 其他設定略...

鍵名	類型	說明
`label`	`String`	按鈕文字
`url`	`String`	按鈕連結 URL

細部設定：近期文章

子表頭：[params.neso.home.list]。

無論你為首頁選擇何種排版模式，都可以額外在下面附加近期文章清單。

鍵名	類型	說明
`featured_entries_limit`	`Integer`	要在首頁顯示的近期文章數量，設為 `0` 則不顯示
`includes_all_sections`	`Boolean`	納入所有 Section 的文章 (預設為 `false`：僅納入 mainSections)
`hide_view_archives_cta`	`Boolean`	隱藏近期文章清單下的「查閱過往文章」按鈕 (該按鈕通往 archives 頁面)

文章清單頁

表頭：[params.neso.list]。

網站內會在各處出現文章清單頁面，例如某個 Section 的文章列表、含有某個 Tag 的文章列表⋯⋯等，以下參數用來設定它們的顯示方式。

鍵名	類型	說明
`prominent_first_entry`	`Boolean`	將列表的第一則文章稍微突出顯示 (純粹外觀點綴)
`provide_rss_for_each_list`	`Boolean`	除了網站首頁外，在所有清單頁面都顯示它們各自的 RSS 按鈕
`hide_page_nums`	`Boolean`	若文章數量多、產生了分頁，此選項可隱藏分頁頁碼
`hide_summary`	`Boolean`	隱藏列表裡文章的內文預覽
`hide_cover_image`	`Boolean`	隱藏列表裡文章的封面圖
`disable_responsive_cover_image`	`Boolean`	列表裡文章的封面圖預設會產生多個圖檔 (透過 Hugo Pipes 於建置期間自動縮圖)，讓瀏覽器依照螢幕尺寸顯示適當的圖檔 `src`，此選項可關閉這個機制、縮短建置時間，但可能犧牲一點瀏覽體驗

單篇文章頁

表頭：[params.neso.page]。

此處參數控制所有單篇文章頁的「整體預設」。部分設定可透過頁面的 Front Matter 覆寫。

提示
舉例來說，如果在這裡透過 show_toc = "false" 把顯示內文目次的功能關了，你仍然可以在某篇文章的 Front Matter 單獨為該篇文章重新啟用目次區塊。對於此類狀況，下方說明會另行附註。

一般設定

鍵名	類型	說明
`ext_link_indicator`	`Boolean`	為文內外連的超連結加上提示 icon
`ext_link_no_opener_referrer`	`Boolean`	為文內外連的超連結 `<a>` 元素加上 `noopener`、`noreferrer` 等 `rel` 屬性值
`ext_link_new_window`	`Boolean`	在新分頁/視窗打開外連的超連結
`hide_description_in_single`	`Boolean`	寫文章時若有填寫 Front Matter 的 `description` 欄位，它除了被拿去用在 SEO 以外 (例如 `<meta>` 標籤)，也會顯示在文章頂部作為前言。此參數可隱藏這類前言區塊，僅作為後設資料供 SEO 使用。
`full_size_cover_image_link`	`Boolean`	寫文章時若有在 Front Matter 設定封面圖，此參數可為封面圖加上連往全尺寸原圖的連結
`show_toc`	`Boolean`	顯示內文目次 (可在頁面的 Front Matter 覆寫此設定)
`toc_expanded`	`Boolean`	預先展開內文目次 (可在頁面的 Front Matter 覆寫此設定)
`disable_heading_links`	`Boolean`	不要為 Markdown 內文的 `## 這類標題` 添加錨點 `<a>` 元素 (類似 GitHub 的 Section links，詳見 Hugo 官方文件)
`enable_comments`	`Boolean`	啟用評論/留言區塊；詳見評論區設定說明 (可透過頁面的 Front Matter 單方面關閉)
`hide_copy_code_button`	`Boolean`	隱藏程式碼區塊的「拷貝」按鈕

頁首文章資訊

文章頁首區塊用來顯示發表日期、作者、字數統計⋯⋯等等的後設資料。部分設定可透過頁面的 Front Matter 覆寫。

鍵名	類型	說明
`show_reading_time`	`Boolean`	顯示閱讀時間估計
`show_word_count`	`Boolean`	顯示字數統計
`show_author`	`Boolean`	顯示作者 (作者資訊可在全站參數設定、或是在 Front Matter 為單篇文章個別設定)
`show_canonical_link`	`Boolean`	如果文章的 Front Matter 有填寫 `canonical_url` 欄位，則將該欄位提供的連結顯示出來
`canonical_link_text`	`String`	顯示 `canonical_url` 連結時，要在開頭加上的預設字串；例如 `原文發表於` (可在頁面的 Front Matter 覆寫此設定)
`hide_metadata`	`Boolean`	隱藏整個頁首區塊 (可在頁面的 Front Matter 覆寫此設定)

文章頁尾區塊用來顯示文章標籤、分享按鈕、繼續閱讀上/下篇等功能。部分設定可透過頁面的 Front Matter 覆寫。

鍵名	類型	說明
`show_content_footer`	`Boolean`	顯示頁尾區塊 (可透過頁面的 Front Matter 單方面關閉)
`show_share`	`Boolean`	顯示分享按鈕 (可透過頁面的 Front Matter 單方面關閉)
`share_providers`	`String[]`	設定分享目標平台；如果有設定，就只會顯示你選用的平台，例如 `["facebook", "line"]`；沒設定的話預設顯示所有平台，即：`["facebook", "line", "linkedin", "messenger", "reddit", "telegram", "whatsapp", "x"]`
`show_prev_next`	`Boolean`	顯示「上/下一篇」文章，供訪客延伸閱讀 (可在頁面的 Front Matter 覆寫此設定)

補充
這裡的「單篇文章頁」指的實際上是 Hugo 所 render 出來的 HTML 頁面，其中大部分設定是針對 page kind 為 page 的頁面——對大多數使用情境來說，通常就是部落格的某篇文章頁面，只是 Hugo 的命名比較抽象，所以姑且稱為單篇文章頁。

SEO

表頭：[params.neso.seo]。

鍵名	類型	說明
`block_indexing`	`Boolean`	將全站所有頁面的 `<meta name="robots">` 設為 `noindex`、`nofollow` (可在頁面的 Front Matter 覆寫此設定)
`site_description`	`String`	網站整體的簡介/描述
`site_keywords`	`String[]`	網站整體的關鍵字清單，例如 `["貓咪", "可愛"]`
`site_author`	`String` `String[]`	網站擁有者/作者名稱；只有一人的話可直接給字串，例如 `"李清照"`，需要顯示多人的話可用字串陣列，例如 `["蘇洵", "蘇軾", "蘇轍"]`

細部設定：結構化資料

子表頭：[params.neso.seo.schema]。

佈景主題會自動幫你生成 JSON-LD 格式的結構化資料，以加強 SEO 表現，以下是一些你可以額外補充的資訊。

鍵名	類型	說明
`publisher_type`	`String`	網站發布者類型，值可為 `Person` 或 `Organization`；更多資訊見 Google 搜尋中心文件，或 Schema.org
`same_as`	`String[]`	其他能代表你的 URL，例如社交平台個人資料頁面、粉絲頁等；更多資訊見 Google 搜尋中心文件，或 Schema.org

細部設定：搜尋引擎認證

子表頭：[params.neso.seo.verification]。

進行 SEO 成效管理的時候，你可能會需要向搜尋引擎驗證你對網站的擁有權。

搜尋引擎通常會提供多種驗證方式，在 HTML 裡插入 <meta> 標籤是其中一種，以 Google 為例，它會提供像這樣的代碼給你：

<meta name="google-site-verification" content="...">

其他搜尋引擎大多也有提供類似機制——總而言之，你取得如上述的驗證原始碼以後，找尋 content 裡面的那串代碼，然後把它貼到下面提供的設定欄位，佈景主題就會自動幫你在網頁原始碼的適當位置插入 <meta> 驗證標籤。

以下是目前可供設定的搜尋引擎：

鍵名	類型	說明
`google`	`String`	Google
`bing`	`String`	Bing
`yandex`	`String`	Yandex
`naver`	`String`	Naver

站內搜尋

表頭：[params.neso.search]。

你需要先將站內搜尋頁面設定妥當，下列設定才有意義；如果你不需要站內搜尋功能，可忽略此處的參數。

鍵名	類型	說明
`input_placeholder`	`String`	顯示在搜尋框的提示字樣

Hugo Pipes 資產管線

表頭：[params.neso.assets]。

佈景主題所用到的一些資源會經過 Hugo Pipes 處理，例如 CSS、JavaScript、部分圖檔等，有時候是為了壓縮轉檔、有時候是為了加上「Fingerprint」以達到 cache busting 的效果，以下提供相關設定選項。

鍵名	類型	說明
`output_dir`	`String`	設定 Hugo Pipes 要將輸出的資源放到發佈目錄下的哪個子目錄 (名稱)，預設為 `"assets"`
`disable_fingerprinting`	`Boolean`	關閉 Fingerprinting

其餘說明

圖像放置處與 URL

上述需要提供圖像 URL 位址的設定皆為以下邏輯：

絕對路徑: 直接使用該 URL 指向的圖檔，可為站內根目錄起算、也可外連。; 例如："/special/stuff.png"、"https://example.com/image.png"。
相對路徑: 建議將圖檔放在 Hugo 專案根目錄下的 assets/ 或 static/ 內 (擇一)，不管你挑哪裡放置，兩者相對路徑寫法都是從它們內部頂層起算。; 舉例來說，將圖檔放在 assets/img/example.png 或 static/img/example.png，最後在設定都是寫 "img/example.png"，佈景主題會自行找到正確位置。惟須注意開頭不要有斜線，否則意義會變成根目錄絕對路徑。; 放在 assets/ 內的話，可支援 fingerprinting。

關於全站設定檔#

頂層設定#

品牌#

社交平台連結#

首頁#

準備 Index 檔案#

選擇排版設計#

細部設定："profile" 模式#

細部設定：近期文章#

文章清單頁#

單篇文章頁#

一般設定#

頁首文章資訊#

頁尾功能#

SEO#

細部設定：結構化資料#

細部設定：搜尋引擎認證#

站內搜尋#

Hugo Pipes 資產管線#

其餘說明#

圖像放置處與 URL#