Skip to main content

Hugo 設定檔

眾所皆知 Hugo 的文檔糟糕透頂，這些概念連他們自己的文檔都寫不好，有多爛看這張圖片就知道了：

Hugo 文檔糟糕的連結指向

source: https://sagar.se/blog/hugo-documentation/

僅僅介紹一個 page bundle 概念就有六步跳轉還有互相 reference 的，非常差勁的文檔編排，而且這張圖從 2022 被做出來到現在問題仍舊沒有被改掉，大概能預期文檔問題永遠不可能改善。

Hugo 很多東西是看主題怎麼用他，主題可以用也可以不用，用了也不見得和文檔講的一樣，有些和 Hugo 內部處理有關，有些只和模板渲染有關，這就造成新手第一印象是不知道這個設定到底在幹嘛。

以下文檔補充是我自己挑出來幾個容易混淆的設定，資訊都基於 v0.165.0 版本。

  • defaultContentLanguage: (a) 決定哪個語言的頁面輸出到網站根目錄、不帶語言前綴；(b) 作為 i18n 翻譯字串查不到時的 fallback 語言依據。
  • v0.161.0 還支援 index._language_en-us_._version_v1.0.0_._role_editor_.md 這種寫法，目前文檔還沒有提到
  • mainSections: Hugo 0.112.0 之前，這個設定是放在 site Params 底下的主題參數，後來被升級成頂層參數，因此才會有設定 params.mainSections 之後卻同時影響 .MainSections 的問題
  • params 的 key 大小寫不敏感。用 site.Params.foo 和 site.Params.Foo 都可以取到 params.Foo。

地區代碼大小寫​

地區代碼，也就是 en-US 或是 zh-TW 後面這兩個後綴到底要大寫還是小寫呢？文檔寫的模糊不清，答案是

  • 依照文檔說明，除了 index.[LANG].md 和 mounts.sites.matrix.languages 以外，應該全部大寫！
  • 實際 go 源碼實現，除了 languageCode（新版稱作 locale）以外其他一律全部小寫！

這兩種都能正確運作...看你喜歡哪種，一種符合文檔但是你根本沒辦法知道哪裡突然又不應該小寫，一種違背文檔但是設定上更統一。

包含很多抱怨的原文

語言的地區代碼到底要大寫還是小寫，這簡單的問題困擾我許久，這麼簡單的問題為什麼文檔到底為什麼不寫？？？到底為什麼可以要 90K stars 了連這種問題看完文檔都還是不知道？？？到處丟 RFC 5646 連結，誰會去看那坨東西？？

罵完了，以下內容大部分都是 Claude 看源碼整理的。

  • defaultContentLanguage: 文檔貼 RFC 5646 連結但是會自動轉小寫...根本不需要理會這個連結。
  • languageCode: 新版稱作 locale，應該要語言代碼小寫，地區代碼大寫 (en-US, zh-TW)。languageCode 和 Hugo 內部系統完全沒有牽扯純粹只用於模板，比如用於 HTML lang 屬性，HTML 規範也應該用地區代碼大寫。
  • languages: 底下的第一層 key 是語言（以下稱作語言鍵），這裡 case 不敏感，內部會直接轉小寫 (common/hmaps/params.go)。
  • contentDir: 他只是 module.mounts 的語法糖幫你設定 module mount，可以隨便你設定任何名稱，並且無論大小寫，構建結果的語言資料夾都是小寫。只要你寫了任何一筆 module.mounts target 是 content，那麼所有語言的 contentDir 都會被忽略。
  • index.[LANG].md: LANG 對應的是 languages 的語言鍵，文檔又不寫...到底為什麼不寫...傻眼。那他應該要大寫還是小寫呢？答案是必須小寫，但是大寫也不會直接報錯，只會被當作不認識的語言處理。
  • v0.161.0 還支援 index._language_en-us_._version_v1.0.0_.md 這種寫法，目前文檔還沒有提到。在這種寫法中，語言會被自動轉小寫。
  • module.mounts.sites.matrix.languages: 必須小寫，不會自動轉換，實際運作會和語言鍵直接字串比較。
  • i18n: i18n/en-US.toml 和 i18n/en-us.toml 都接受，被視為同一種語言。

defaultContentLanguage 和 languages 語言鍵（底下第一層 key）強制轉小寫，index.[LANG].md 以及 mounts.sites.matrix.languages 會和語言鍵直接字串比對，必須違背 RFC 5646 才會和語言鍵比對成功，languageCode (locale) 與是純模板與內部無關，contentDir 隨便你設定但是構建輸出一律小寫，一個語言功能到底要有幾種不同規則？文檔內容也是錯的

  1. Language keys must conform to the syntax described in RFC 5646: 不是必須的，Hugo 會強制轉小寫。
  2. Artificial languages with private use subtags as defined in RFC 5646 § 2.2.7 are also supported. Omit the art-x- prefix from the language key: 根本沒有用到該規範的東西就不要把規範拿出來講，完全在混淆人，實際上 [languages.hugolang] 不需要 art-x- 前綴就已經是違反規範，i18n 目錄也是直接用 hugolang.toml 同樣不需要 art-x- 前綴，同樣違反規範

總結下來這些幾乎全都會被強制轉小寫，實際上運作也多是和語言鍵比較字串值，內部根本就不管那些規範，遇到嚴格檢查格式的第三方套件也都是臨時把字串加上送進去，回傳出來又馬上移除，我也理解這樣比較方便，但是你根本就不理這些東西，那文檔就不要到處寫 5646 嚇人。

更新日期：