今天老馮又讓 Claude Code 干了一件大好事 —— 做了一個全新的 PostgreSQL 擴(kuò)展目錄。就放在 https://pigsty.cc/ext 這里。

說起來，這已經(jīng)是第五版了。兜兜轉(zhuǎn)轉(zhuǎn)一大圈，又回到了第一版使用的 Hugo + Docsy 框架，重新融合到 Pigsty 主站。這個過程本身就是個故事，后面再聊。先說說這一版到底做了什么。

不只是有包，還要有文檔

之前的擴(kuò)展目錄，核心功能是告訴你：這個擴(kuò)展叫什么、元數(shù)據(jù)在哪里、二進(jìn)制包怎么下載、一鍵安裝怎么搞。你裝好了就行，至于怎么用 —— 自己找文檔去。

這次不一樣了。在 AI 的幫助下，我們開始系統(tǒng)性地收集并翻譯這 464 個擴(kuò)展的文檔，目標(biāo)是讓你在一個地方就能看到所有擴(kuò)展最關(guān)鍵的使用信息。

具體來說，分兩種情況：

對于文檔體量巨大的"巨無霸"擴(kuò)展，我們會建立專門的子站點(diǎn)來做翻譯。比如 Citus、TimescaleDB、PostGIS 這幾個，文檔量本身就相當(dāng)于一本書，值得單獨(dú)對待。

對于大多數(shù)輕量級擴(kuò)展，情況其實(shí)很簡單 —— 它們的全部文檔往往就是一頁 README。比如 pgvector，作為 PG 生態(tài)中最炙手可熱的向量數(shù)據(jù)庫擴(kuò)展，文檔就一頁紙；

再比如 pg_repack，這個在線治理表膨脹的運(yùn)維利器，文檔也就是一頁 Markdown。

我們要做的，就是把這些 README 統(tǒng)統(tǒng)收集起來，嵌入到每個擴(kuò)展的詳情頁面中。你不用再到處跳轉(zhuǎn)、翻 GitHub，在一個集中的地方就能查閱所有擴(kuò)展的核心文檔。對于特別大的擴(kuò)展，我們也會把信息索引聚合起來，讓你有一個權(quán)威可靠的參考入口。

目前 pigsty.cc 已經(jīng)。后續(xù)所有擴(kuò)展 —— 包括 PostgreSQL 內(nèi)核本身 —— 都會逐步推進(jìn)并持續(xù)維護(hù)。

這也是我們的一個愿景：成為 PG 生態(tài)中關(guān)鍵信息的可靠來源。

說實(shí)話，很多時候我做"正活"剩下的 AI Token 額度沒燒完，就順手拿來填這些空，算是一種兜底，也算在做公益。

同時對 Agent 友好，對人類友好

接下來聊聊這個目錄是怎么設(shè)計的。

雖然技術(shù)棧兜了一圈又回到 Hugo + Docsy，但在 Claude Code 的加持下，純靜態(tài)網(wǎng)站也能做出非常出色的效果。設(shè)計上，老馮遵循一個核心原則：同時對 AI Agent 友好，對人類讀者友好。

對 Agent 友好，意味著網(wǎng)頁的源碼是開源的、采用 Markdown 格式，而且有一個硬性要求：減少雜音。Markdown 里不應(yīng)該混入大量原生 HTML 短代碼或格式噪聲，否則會給 Agent 的解析和閱讀制造很大障礙。

對人類讀者友好，意味著要把信息高效組織為美觀的可視化形式，讓人能直觀地發(fā)現(xiàn)問題、聚焦關(guān)鍵信息。

舉個具體例子：這一版我們做了一個很實(shí)用的嘗試 —— 將所有擴(kuò)展融合進(jìn)一張大表格。在特定的 PG 版本和操作系統(tǒng)組合下，你可以通過單元格直接看到有多少個可用的包、來自哪個倉庫，點(diǎn)擊即可下載，非常方便。

但是老馮并沒有去用很復(fù)雜的 HTML 來實(shí)現(xiàn)，依然用的是標(biāo)準(zhǔn)的 Markdown 格式，只是在外面套了一層短代碼進(jìn)行必要的內(nèi)容轉(zhuǎn)換。這個在 Hugo 編譯的時候進(jìn)行必要的內(nèi)容轉(zhuǎn)換，然后通過定制的 CSS 格式，讓它呈現(xiàn)出可觀的效果。

同時我們這次也提供了一系列分門別類的列表索引，從不同維度展示擴(kuò)展的屬性信息，方便快速檢索定位。站內(nèi)搜索也比之前的版本好用了不少。

另外，這次我們還將一些 PG 內(nèi)核分支獨(dú)有的擴(kuò)展也收錄了進(jìn)來：

五個版本，兜兜轉(zhuǎn)轉(zhuǎn)回到原點(diǎn)

最后聊一個不那么技術(shù)、但挺有感觸的話題：文檔框架的選型。

這個擴(kuò)展目錄從第一版到現(xiàn)在，前后經(jīng)歷了五個版本：

1.Hugo + Docsy（初版，融合在 Pigsty 主站）2.Docsify3.Next.js4.Hugo + Hextra（獨(dú)立站點(diǎn) pgext.cloud）5.Hugo + Docsy（現(xiàn)在，回歸 Pigsty 主站）

中間那個獨(dú)立站點(diǎn) pgext.cloud，因?yàn)闆]有備案、掛在 Cloudflare 上，有國內(nèi)用戶反饋訪問不穩(wěn)定，懷疑被墻。思來想去，還是老老實(shí)實(shí)用備案過的域名來做這件事。

第一版：基于 Hugo + Docsy （和這次一樣）

第二版：基于 Docsify

第三版：基于 Next.js + Fumadocs

后來實(shí)在受不了動態(tài)網(wǎng)站的一堆破事，回歸靜態(tài)網(wǎng)站了。

第四版：基于 Hugo + Hextra

Hextra 是另一個輕量化的，類似 Fumadocs 的主題。我很喜歡，它對于小型項(xiàng)目來說非常合適，比如翻譯書什么的。但是對于大型文檔站點(diǎn)來說還是有些力不從心。但是老馮的幾本書，教程，小項(xiàng)目都很喜歡用這個框架。

這次掛在了獨(dú)立站點(diǎn) pgext.cloud 三，因?yàn)闆]有備案、掛在 Cloudflare 上，有國內(nèi)用戶反饋訪問不穩(wěn)定，懷疑被墻。思來想去，還是老老實(shí)實(shí)用備案過的域名來做這件事。

第五版： Hugo + Docsy

最終的結(jié)論其實(shí)很簡單：

如果你要做靜態(tài)文檔站，選 Hugo 就行了。Docsy是 Google 出品的主題，Kubernetes 和 etcd 的文檔都在用，基本功扎實(shí)，搜索好用，結(jié)構(gòu)清晰，到現(xiàn)在還在活躍更新。輕量級的場景可以用 Hextra，重量級的就上 Docsy。如果需要做內(nèi)容豐富的動態(tài)網(wǎng)站，Next.js 可以考慮，但它有時候確實(shí)挺重的。

Hugo 這個框架我用了快十年，從來沒讓我失望過。折騰了這么多新玩意，最后發(fā)現(xiàn)六七年前第一次選的框架就是最合適的選擇。這大概也印證了一個道理：扎實(shí)的 Boring Technology 才是最好的。網(wǎng)站不在于做得多炫酷，而在于里面的信息有沒有價值。內(nèi)容為王，始終沒變。

你要說這些折騰的時間拿去做視頻教程、寫實(shí)戰(zhàn)案例，是不是更有價值？也許吧。但折騰一圈回來，你知道了有哪些選擇、它們各自的利弊權(quán)衡，提升了自己的 Web 設(shè)計經(jīng)驗(yàn)與品位 —— 這本身就是一種收獲。

誰說得準(zhǔn)呢？折騰本身，也蠻有樂趣的。