今天老馮又讓 Claude Code 干了一件大好事 —— 做了一個(gè)全新的 PostgreSQL 擴(kuò)展目錄。就放在 https://pigsty.cc/ext 這里。
說(shuō)起來(lái),這已經(jīng)是第五版了。兜兜轉(zhuǎn)轉(zhuǎn)一大圈,又回到了第一版使用的 Hugo + Docsy 框架,重新融合到 Pigsty 主站。這個(gè)過(guò)程本身就是個(gè)故事,后面再聊。先說(shuō)說(shuō)這一版到底做了什么。
不只是有包,還要有文檔
之前的擴(kuò)展目錄,核心功能是告訴你:這個(gè)擴(kuò)展叫什么、元數(shù)據(jù)在哪里、二進(jìn)制包怎么下載、一鍵安裝怎么搞。你裝好了就行,至于怎么用 —— 自己找文檔去。
這次不一樣了。在 AI 的幫助下,我們開(kāi)始系統(tǒng)性地收集并翻譯這 464 個(gè)擴(kuò)展的文檔,目標(biāo)是讓你在一個(gè)地方就能看到所有擴(kuò)展最關(guān)鍵的使用信息。
具體來(lái)說(shuō),分兩種情況:
對(duì)于文檔體量巨大的"巨無(wú)霸"擴(kuò)展,我們會(huì)建立專門的子站點(diǎn)來(lái)做翻譯。比如 Citus、TimescaleDB、PostGIS 這幾個(gè),文檔量本身就相當(dāng)于一本書,值得單獨(dú)對(duì)待。
對(duì)于大多數(shù)輕量級(jí)擴(kuò)展,情況其實(shí)很簡(jiǎn)單 —— 它們的全部文檔往往就是一頁(yè) README。比如 pgvector,作為 PG 生態(tài)中最炙手可熱的向量數(shù)據(jù)庫(kù)擴(kuò)展,文檔就一頁(yè)紙;
![]()
再比如 pg_repack,這個(gè)在線治理表膨脹的運(yùn)維利器,文檔也就是一頁(yè) Markdown。
![]()
我們要做的,就是把這些 README 統(tǒng)統(tǒng)收集起來(lái),嵌入到每個(gè)擴(kuò)展的詳情頁(yè)面中。你不用再到處跳轉(zhuǎn)、翻 GitHub,在一個(gè)集中的地方就能查閱所有擴(kuò)展的核心文檔。對(duì)于特別大的擴(kuò)展,我們也會(huì)把信息索引聚合起來(lái),讓你有一個(gè)權(quán)威可靠的參考入口。
目前 pigsty.cc 已經(jīng)。后續(xù)所有擴(kuò)展 —— 包括 PostgreSQL 內(nèi)核本身 —— 都會(huì)逐步推進(jìn)并持續(xù)維護(hù)。
這也是我們的一個(gè)愿景:成為 PG 生態(tài)中關(guān)鍵信息的可靠來(lái)源。
說(shuō)實(shí)話,很多時(shí)候我做"正活"剩下的 AI Token 額度沒(méi)燒完,就順手拿來(lái)填這些空,算是一種兜底,也算在做公益。
同時(shí)對(duì) Agent 友好,對(duì)人類友好
接下來(lái)聊聊這個(gè)目錄是怎么設(shè)計(jì)的。
雖然技術(shù)棧兜了一圈又回到 Hugo + Docsy,但在 Claude Code 的加持下,純靜態(tài)網(wǎng)站也能做出非常出色的效果。設(shè)計(jì)上,老馮遵循一個(gè)核心原則:同時(shí)對(duì) AI Agent 友好,對(duì)人類讀者友好。
對(duì) Agent 友好,意味著網(wǎng)頁(yè)的源碼是開(kāi)源的、采用 Markdown 格式,而且有一個(gè)硬性要求:減少雜音。Markdown 里不應(yīng)該混入大量原生 HTML 短代碼或格式噪聲,否則會(huì)給 Agent 的解析和閱讀制造很大障礙。
對(duì)人類讀者友好,意味著要把信息高效組織為美觀的可視化形式,讓人能直觀地發(fā)現(xiàn)問(wèn)題、聚焦關(guān)鍵信息。
![]()
舉個(gè)具體例子:這一版我們做了一個(gè)很實(shí)用的嘗試 —— 將所有擴(kuò)展融合進(jìn)一張大表格。在特定的 PG 版本和操作系統(tǒng)組合下,你可以通過(guò)單元格直接看到有多少個(gè)可用的包、來(lái)自哪個(gè)倉(cāng)庫(kù),點(diǎn)擊即可下載,非常方便。
但是老馮并沒(méi)有去用很復(fù)雜的 HTML 來(lái)實(shí)現(xiàn),依然用的是標(biāo)準(zhǔn)的 Markdown 格式,只是在外面套了一層短代碼進(jìn)行必要的內(nèi)容轉(zhuǎn)換。這個(gè)在 Hugo 編譯的時(shí)候進(jìn)行必要的內(nèi)容轉(zhuǎn)換,然后通過(guò)定制的 CSS 格式,讓它呈現(xiàn)出可觀的效果。
![]()
同時(shí)我們這次也提供了一系列分門別類的列表索引,從不同維度展示擴(kuò)展的屬性信息,方便快速檢索定位。站內(nèi)搜索也比之前的版本好用了不少。
![]()
![]()
![]()
![]()
![]()
![]()
![]()
另外,這次我們還將一些 PG 內(nèi)核分支獨(dú)有的擴(kuò)展也收錄了進(jìn)來(lái):
![]()
五個(gè)版本,兜兜轉(zhuǎn)轉(zhuǎn)回到原點(diǎn)
最后聊一個(gè)不那么技術(shù)、但挺有感觸的話題:文檔框架的選型。
這個(gè)擴(kuò)展目錄從第一版到現(xiàn)在,前后經(jīng)歷了五個(gè)版本:
1.Hugo + Docsy(初版,融合在 Pigsty 主站)2.Docsify3.Next.js4.Hugo + Hextra(獨(dú)立站點(diǎn) pgext.cloud)5.Hugo + Docsy(現(xiàn)在,回歸 Pigsty 主站)
中間那個(gè)獨(dú)立站點(diǎn) pgext.cloud,因?yàn)闆](méi)有備案、掛在 Cloudflare 上,有國(guó)內(nèi)用戶反饋訪問(wèn)不穩(wěn)定,懷疑被墻。思來(lái)想去,還是老老實(shí)實(shí)用備案過(guò)的域名來(lái)做這件事。
第一版:基于 Hugo + Docsy (和這次一樣)
![]()
第二版:基于 Docsify
![]()
第三版:基于 Next.js + Fumadocs
![]()
后來(lái)實(shí)在受不了動(dòng)態(tài)網(wǎng)站的一堆破事,回歸靜態(tài)網(wǎng)站了。
第四版:基于 Hugo + Hextra
Hextra 是另一個(gè)輕量化的,類似 Fumadocs 的主題。我很喜歡,它對(duì)于小型項(xiàng)目來(lái)說(shuō)非常合適,比如翻譯書什么的。但是對(duì)于大型文檔站點(diǎn)來(lái)說(shuō)還是有些力不從心。但是老馮的幾本書,教程,小項(xiàng)目都很喜歡用這個(gè)框架。
這次掛在了獨(dú)立站點(diǎn) pgext.cloud 三,因?yàn)闆](méi)有備案、掛在 Cloudflare 上,有國(guó)內(nèi)用戶反饋訪問(wèn)不穩(wěn)定,懷疑被墻。思來(lái)想去,還是老老實(shí)實(shí)用備案過(guò)的域名來(lái)做這件事。
第五版: Hugo + Docsy
![]()
最終的結(jié)論其實(shí)很簡(jiǎn)單:
如果你要做靜態(tài)文檔站,選 Hugo 就行了。Docsy是 Google 出品的主題,Kubernetes 和 etcd 的文檔都在用,基本功扎實(shí),搜索好用,結(jié)構(gòu)清晰,到現(xiàn)在還在活躍更新。輕量級(jí)的場(chǎng)景可以用 Hextra,重量級(jí)的就上 Docsy。如果需要做內(nèi)容豐富的動(dòng)態(tài)網(wǎng)站,Next.js 可以考慮,但它有時(shí)候確實(shí)挺重的。
Hugo 這個(gè)框架我用了快十年,從來(lái)沒(méi)讓我失望過(guò)。折騰了這么多新玩意,最后發(fā)現(xiàn)六七年前第一次選的框架就是最合適的選擇。這大概也印證了一個(gè)道理:扎實(shí)的 Boring Technology 才是最好的。網(wǎng)站不在于做得多炫酷,而在于里面的信息有沒(méi)有價(jià)值。內(nèi)容為王,始終沒(méi)變。
你要說(shuō)這些折騰的時(shí)間拿去做視頻教程、寫實(shí)戰(zhàn)案例,是不是更有價(jià)值?也許吧。但折騰一圈回來(lái),你知道了有哪些選擇、它們各自的利弊權(quán)衡,提升了自己的 Web 設(shè)計(jì)經(jīng)驗(yàn)與品位 —— 這本身就是一種收獲。
誰(shuí)說(shuō)得準(zhǔn)呢?折騰本身,也蠻有樂(lè)趣的。
![]()
特別聲明:以上內(nèi)容(如有圖片或視頻亦包括在內(nèi))為自媒體平臺(tái)“網(wǎng)易號(hào)”用戶上傳并發(fā)布,本平臺(tái)僅提供信息存儲(chǔ)服務(wù)。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.