本文探討如何利用 AI 工具與 Python 腳本，將文檔從需付費綁定網域的 GitBook 遷移至 Jekyll 靜態網站。內容涵蓋自動化爬取、Markdown 格式修正、CSS 樣式調整，以及如何透過 Cloudflare Pages 與 Git 建立更流暢的多語系維護流程，省下高額訂閱費並解決輸入法卡頓問題。
對於許多開發者或技術寫作者來說，維護一份清晰、美觀的產品文檔是日常工作的一部分。GitBook 曾是許多人的首選，它提供了直觀的 UI 和便捷的協作功能。然而，當工具的收費模式改變，或是使用體驗不再符合需求時，尋找替代方案便成了必然的選擇。
最近，在嘗試調整 dmflow.chat 的文檔時，遇到了一個令人猶豫的情況：GitBook 的自訂網域（Custom Domains）功能現在需要訂閱 Premium 方案。對於一個僅需要展示靜態內容、不需要複雜反饋功能、和私有的內容的站點來說，每個站點每月 65 美元的開銷，若涉及多個語系專案，成本確實不低。
此外，長期使用 GitBook 的過程中，也發現了一些影響效率的小問題。例如在維護中英文多語系版本時，需要在不同區塊間切換，相當耗時。更困擾的是，使用注音輸入法在 GitBook 的 UI 上編輯時，偶爾會出現第一個字卡住的狀況，導致必須重新整理頁面才能繼續。既然舊文檔最後一次編輯已是數個月前，將文檔遷移回官網自行託管，似乎是一個既省錢又能優化工作流的決定。
為什麼選擇遷移至 Jekyll 與 Cloudflare Pages
因為本來的站點就是使用Jekyll建置的，由於沒有特別多的文章，所以仍是保留Jekyll，但我還是建議大家使用Hugo搭建靜態網頁。
決策的核心在於「掌控權」與「成本效益」。原本的文檔網站 docs.dmflow.chat 其實並沒有太高的 SEO 權重，因此將內容移動到主網域下的子目錄（如 www.dmflow.chat/tw/docs）並不會造成太大的流量損失。舊的子網域可以直接設定轉址，將所有請求導向新的位置，簡單粗暴但有效。
選擇 Jekyll 作為靜態網站產生器（Static Site Generator），搭配 Cloudflare Pages 進行託管，是目前相當流行的輕量化組合。Cloudflare Pages 提供了極佳的連線速度與穩定的部署環境，且對於靜態網站幾乎是免費的。更重要的是，回歸到本地端的 Markdown 檔案管理，意味著可以使用任何喜歡的編輯器，徹底告別線上編輯器的輸入法延遲問題。
利用 AI 與 Python 實現自動化爬取
要將已經寫好的大量文檔手動複製貼上，顯然不是聰明的做法。這時候，自動化工具就派上用場了。在這個案例中，我是直接使用 antigravity 的工具，展現了身為「專業懶人」的智慧。
透過讀取原網站的 sitemap-pages.xml，可以獲取所有頁面的連結。接著，利用 Python 編寫腳本，不僅能抓取頁面上的文字內容，還能將圖片一併下載並整理好路徑。這種方式能確保內容的完整性，避免人工搬運時的遺漏。與其花費數小時手動複製，不如花幾十分鐘寫好腳本，讓機器去處理重複性的勞動。
Markdown 格式修正與樣式調整
雖然爬蟲能抓取內容，但從 GitBook 匯出的 HTML 轉回 Markdown，或是直接抓取的內容，往往需要後續的整理。這裡主要涉及幾個層面的調整：
- YAML Front Matter 的修復：Jekyll 依賴文件頂部的 YAML 區塊來定義標題、佈局和固定連結。爬下來的檔案通常缺乏這部分，或者格式混亂，需要重新標準化。
- HTML 標籤的轉換：GitBook 可能會在 Markdown 中混入特定的 span 或 div 標籤。在 Jekyll 中，這些需要透過調整 CSS 來適配。
- 視覺呈現的優化：為了讓閱讀體驗接近甚至超越原本的 GitBook，需要針對
table、h2到h5等標籤調整 CSS 樣式。確保表格在手機版能橫向捲動，標題的字體大小與間距適中。 - SEO 資訊的補全：在遷移過程中，順手為每個頁面加上正確的 Meta Title、Description 以及最後修改時間，這對於搜尋引擎的爬取非常有幫助。
在使用 AI 輔助修復 Markdown 檔時，有個小插曲值得注意。有時 AI 在處理文檔時，會不小心刪除 Jekyll 必須的 YAML 區塊，或是移除了分隔用的 --- 符號。這需要開發者在自動化處理後進行簡單的檢查。
簡化結構與多語系管理的未來
原本 GitBook 支援多層級的目錄結構，但在遷移到 Jekyll 的過程中，為了讓 YAML 的管理更方便，選擇將結構扁平化，僅保留單層目錄。這或許算是一個小小的妥協，但換來的是維護上的極度簡化。
最大的改變在於多語系的維護流程。以往需要同時開啟中文與英文的 GitBook 專案，逐個區塊對照翻譯。現在，透過 Git 進行版本控制，所有的文檔都只是 repo 中的檔案。
當完成中文版本的撰寫後，可以直接將 Markdown 檔案交給 AI 進行翻譯。AI 能精準地將內容轉換為英文，並保留 Markdown 的語法結構。開發者不再需要手動去英文站點一個一個區塊地替換內容。整個流程變成了：本地撰寫 -> Git 推送 -> Cloudflare Pages 自動構建，既流暢又高效。
結論
這次從 GitBook 遷移至自建 Jekyll 站點的過程，證明了只要善用工具，擺脫平台綁定並非難事。雖然犧牲了 GitBook 原生的 UI 編輯功能和部分多層級目錄的便利性，但換來的是直接用AI編寫內容和翻譯、更快的網站載入速度，以及一個完全可控、無輸入法 bug 的寫作環境。對於技術文檔維護者而言，這是一次值得參考的「降本增效」實踐。
常見問題解答 (FAQ)
Q：為什麼要放棄 GitBook 轉而使用 Jekyll？ 主要考量是成本與使用體驗。GitBook 的自訂網域功能改為收費項目（Premium），且其線上編輯器在使用注音輸入法時偶有卡頓。轉用 Jekyll 配合 Cloudflare Pages，不僅能免費託管靜態網站，還能透過本地編輯器解決輸入延遲的問題。
Q：遷移後的網站結構與原本有什麼不同？ 為了簡化 Jekyll 的 YAML 設定與管理難度，遷移後的文檔結構選擇了單層目錄，而非 GitBook 的多層巢狀結構。雖然層級變少，但對於維護與讀者檢索來說，反而更加直觀且易於管理。
Q：如何解決多語系文檔的翻譯與維護問題？ 不再需要手動在兩個不同的 GitBook 專案中同步內容。現在只需維護中文版本的 Markdown 檔案，利用 AI 工具將其翻譯成英文，再透過 Git 進行版本控制與發布。這大幅減少了重複勞動，讓多語系維護變得輕鬆許多。
Q：遷移過程中使用了哪些技術工具？ 使用了名為 antigravity 的工具自行撰寫 Python 腳本來爬取原網站的 sitemap、內容與圖片。後續則透過它幫我們在 CSS 調整來優化 Markdown 在 Jekyll 上的渲染效果，包括表格樣式與標題排版。