我不斷重申過多次文檔問題，請注意我不是路邊隨便一個普通用戶，我是一個自己使用 Hugo 架站，又維護一個知名主題，自己還額外寫了三個 Hugo 主題的人，文檔的問題從我第一天使用 Hugo 到我維護主題，開新主題，這問題之於我從 noob 到 developer 階段都不斷重複遇到。

這是文檔的原文，請設身處地的、不做防禦性思維的幫讀者著想，你能想到最預設、沒有任何設定的初始網站範本，render hook 最後會調用誰嗎？

renderHooks.link.useEmbedded

(string) When to use the embedded link render hook. One of auto, never, always, or fallback. Default is auto.

• auto: Automatically use the embedded link render hook for multilingual single-host sites, specifically when the duplication of shared page resources feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
• never: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
• always: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes. In this case, the embedded hook takes precedence.
• fallback: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead.

網站全空的情況下實際效果等同於 never，永遠不使用 embedded。

monolingual 網站是最基礎的場景，恐怕也是大多數用戶的場景，結果基本場景在文檔反而找不到，他說預設使用 auto，然而 auto 裡面全都在說 multilingual，也沒有明確指出僅限用於多語言，哪個文檔不從簡單的開始反而從難的開始？哪個用戶不會預期啥都不做就會使用內建的？有特殊原因預設情況不用內建我完全能理解，那就好好寫出來，哪個文檔需要讀者反向思維？尤其是在一個超過兩千字的文檔裡面？甚至是你不反向思維還找不到答案？

最直觀的例子就是文檔就連基礎中的基礎，主題安裝以及自身特色優勢都解釋不清，一堆人搞錯使用方式，就可以驗證我不是胡說八道亂黑一通。

具體來說，Hugo 最顯著的一個優勢是 UFS override 系統，以及主題使用 git submodule 安裝，但是我已經回答過不知道多少次用戶錯誤的安裝方式、錯誤的修改主題原始碼、錯誤的覆蓋主題檔案了，這些問題都是在主題端就幫他擋下來的，而且回應的多之後我也發現搞錯的人不只是非技術人員，有技術菜鳥搞錯的，也有很多博士生需要架站的也搞錯，甚至偶爾還能糾正幾個正職是前端、後端的工程師也以錯誤的方式使用，你要是寫的清楚，有可能連這種高水準族群都搞混嗎，別忘了我不是什麼高要求，這只是最最最最最最最最基礎的主題安裝和重大特色介紹，我不知道還要幾個最才能表示這有多基礎。

退十萬步講，你說文檔要是只有現在這一個「文字描述不清」的問題也就算了，問題這文檔的問題是系統性的，不然我怎麼有辦法提系統性的建議？至於提的建議又接收到怎麼樣的回應，別篇文章有寫到。

就算不是個人用戶，你拿企業用戶來說好了，要是真的有達到低標水準，那為什麼 Cloudflare/2k Games 那些曾經使用 Hugo 建立網站的大企業為什麼最後都跳槽使用 Astro？甚至 Cloudflare 還收購 Astro？那不就是上手問題和黑盒子問題嗎，Astro 才出來多久而已，企業最需要的就是穩定可靠，但是人家寧願換成一個新穎、不到兩年的工具，也不想用你一個開發 10 年的工具，最後被放棄的是 Hugo，這說明什麼？就連開源的 Bootstrap 也放棄 Hugo，描述遷移原因的#38319裡也抱怨文檔，Hacker News 也非常多篇文章在抱怨文檔。

現在你知道為什麼我回報 Hugo 問題總是直接描述 reproducible steps 了吧，因為根本就不知道哪一個地方又有奇怪的怪癖，不知道哪裡出問題只好直接回報重現步驟，這不是我一個人的感想，Hacker News 裡面也有人說出完全一樣的話。

說個笑話，初學者看著 Hugo 文檔安裝啟動之後，你馬上就不知道下一步該做什麼了，因為 configuration 直接丟給你 reference page，裡面有上百個設定，沒有解釋 params 和其他設定的不同，甚至沒有幫 override 寫一個獨立段落，他在整個文檔裡面只是在 getting started 最下面的三行文字，我甚至還用 grep 檢查過我有沒有遺漏，因為我要貼文檔給用戶然後發現根本沒獨立段落（當時我甚至是把文檔網站 clone 下來然後 grep 各種可能關鍵字確認，這本身就是一件非常荒謬的事情，哪個文檔需要這樣搞？）