Hugo 雖然有顯著的缺點，比如說我在 SSG 比較 這篇文章就說過 Hugo 文檔很糟糕，但是開發者非常熱心的回應，甚至看原始碼找問題是我沒有想到的，然而本文的起因還是來自文檔。

背景

維護 Blowfish 主題時由於頁面超過 1400 頁，所以我希望能開發時透過環境變數排除語言和指定資料夾以加快速度。我的想法是：

1. 使用 HUGO_DISABLELANGUAGES 排除不需要的語言
2. 使用某種方式排除指定資料夾（如 /users/）

文檔的問題

先說文檔有哪些問題，有了這些認知之後，接下來再看前因後果會比較能體會為什麼簡單的問題可以搞成這樣。

文檔 header nav 點進去 會看到 card 風格的文檔頁面，這裡的 card 排序是依照字母，再點進不同的文檔內容，有些是依照字母排序，有些依照重要程度排序，有些不規則，要不是為了寫這篇文章我也不會發現這件事，誰沒事會去研究文檔的順序是怎麼排的，對於文檔這個問題很大，因為讀者沒辦法有邏輯的閱讀，也造成維護者很大的負擔，例如要回答我的笨問題。沒錯，我搞懂後馬上就覺得自己的問題很愚蠢，但是我還是認為這是文檔造成的問題，下一個人來也會遇到一樣的事情。

除了排序問題以外，右邊 ToC 一次顯示 In this section 和 On this page，兩個樣式完全一樣，要馬點擊連結之前還要腦袋清醒看清楚是哪種清單，要馬點進去看會不會切換頁面。

前因後果

前面說完文檔難以閱讀的前提後，這裡說明整件事的經過。

1. 我發現 Hugo 可以透過環境變數在開發時修改設定，對於需要頻繁切換開發配置的場景非常有用。
2. 我發現 disableLanguages 可以關閉指定語言，使用 HUGO_DISABLELANGUAGES=it ja zh-cn 設定，這樣就少掉 3/4 頁面，剩下 350 頁要渲染。
3. blowfish 主題有 100 多頁都在 users 目錄中，於是我繼續在設定頁面尋找 disable ignore no 之類的排除關鍵字。
4. 裡面唯一相似的只有 ignoreFiles，然而以環境變數輸入時，使用空隔作為路徑的 delimiter 顯然不可能，我又嘗試了幾種不同設定，確認 Hugo 的確不支援在 ignoreFiles 的環境變數分割多個字串。
5. 剛好前兩天我也發了 類似的 bug report，於是就趁機提 proposal Use colon as separator for environment variables 說明優點，我即使到現在也覺得這個提案不錯，因為符合 POSIX 傳統，也能在 Windows 上使用，而誤會也從這裡開始展開。

我的目的其實很簡單，只是要避免指定目錄被處理，但是前面的經歷讓我的思維被導向成「讓環境變數使用 delimiter 以支援輸入列表」，這和我的原始目的不符合，導致我發了一個看似相關但是會讓人困惑的 issue。

我沒有要推卸責任，錯的確在我，但是因為文檔沒辦法讓人照順序讀，例如開發者回應我應該要用 segment 完成而不是 ignoreFiles，那麼以下是整個 config section 的目錄，大家可以找找看 segments 在哪：

• Introduction <— 介紹放在最前面，看起來是按照重要程度排序？
• All settings <— 我現在在這裡
• Build <— 順序又變成字母排序了
• Caches
• Cascade
• Content types
• Deployment
• Front matter
• HTTP cache
• Imaging
• Languages
• Markup
• Media types
• Menus
• Minify
• Modules
• Output formats
• Outputs
• Page
• Pagination
• Params
• Permalinks
• Privacy
• Related content
• Security
• Segments <— segments 在這裡
• Server
• Services
• Sitemap
• Taxonomies
• Ugly URLs

我都已經找到 ignoreFiles 可以解決問題了，只差臨門一腳他的環境變數設定有問題，哪有可能又把整個設定章節看完，而且他還在最後面，要注意文檔是卡片設計而不是一目了然的列表設計，甚至這還只是其中一個章節，文檔總共有 20 個 section，正常人根本不可能把文檔翻個遍。

更笨的發問

總之開發者回應說可以用 segments 後我就著手修改，看 segments 文檔第一句話又是模糊的

The segments configuration applies only to segmented rendering. While it controls when content is rendered, it doesn’t restrict access to Hugo’s complete object graph (sites and pages), which remains fully available.

能懂在某些情況下還是會處理這些資源，但是就是用猜的，不過不懂就算了先跳過能動再說，先去看範例，接下來一半時間測試設定檔，另一半時間在想文檔裡面提到的 Filter Matcher 到底是什麼，沒錯，文檔直接定義了兩個新名詞但是沒說他對應到哪個參數，在設定檔裡面我們寫的是 segment_name include exclude，又要開始猜文檔，這雖然不難猜，但是文章也就沒超過 30 行，怎麼不直接說 Matcher 就是 include，Filter 就是 exclude。

結果 HTML 頁面被排除但是圖片還是會被渲染，所以我提了一個更笨的問題問他為何圖片還是被渲染，原因是被我跳過的 object graph，事情到此結束，issue 也被關閉，浪費他這麼多時間我感到很抱歉，但是這個鍋有一半要給文檔背。

再次強調 Hugo 的開發者人很好，但是文檔問題很大才造成這些時間浪費。

失敗的提問經驗

1. 我沒有找出我的核心問題，我要的是在命令行中隨時修改忽略的內容，而不該提案 colon。
2. 我應該說明我要的很單純，能在命令行直接忽略多個指定目錄，因為 segments 設計和我的需求不同，這樣開發者可能還有耐心回應。
3. 就算文檔很難讀還是該丟給 AI 整理，這樣可以省下大家時間。
4. 再次感謝開發者，完全沒有想到會這麼熱心的回應，甚至讀原始碼跟我說哪裡有問題，這裡多次強調我只有抱怨文檔，其餘我都是讚賞的。