在Github上有一個功能叫做Github Pages，提供了免費的網頁託管(有限制建立的數量)是靜態網頁的形式，而我呢 小時後玩Google sites，後來國中和人組隊搞WIX+Fandom(雖然收掉了) 現在則是想要自己建立一個屬於我自己的，沒有數據壓力且高度客製化的網頁。
所以，我開始了自己建立網頁的旅途
工具
若要使用GithubPage，需要準備以下:
GitHub 帳號：都叫GithubPage了沒有帳號怎麼行
Git： 版本控制，避免發生重大事故無法回滾
Ruby (含 Devkit)： Jekyll 的核心。
在 Windows 環境下，務必安裝帶有 Devkit 的版本，才能順利編譯各種套件
這是本機預覽的基礎
(同時也結省時間，不然每次改動什麼Github都要重新跑一次整個網頁很麻煩)
GitHub CLI： 在終端機就能操作 GitHub 的方便工具
Node.js (選用)： 許多現代主題用它來處理 CSS/JS。 我的主題最後沒用到這部分，若是要深度客製化前端樣式這是繞不開的一環
AI(推薦Claude+Gemini):解決問題的好幫手，切記 不要用普通版的介面
用Google AI studio 超長上下文+Pro模型會減少很多麻煩
從0開始
發生了什麼事?
最初的計畫很單純：先用Jekyll 預設主題建立一個乾淨的基礎 再將高度客製化的主題無痛轉移過去。但是在實際操作的過程中發現有需多問題不能直接換，所以呢 整個重新開一個倉庫
主題客製化
這個部分可以做，但在做之前請先確認還沒建立起倉庫 那這次客制呢，是找Claude參考brand-guidelines這個官方Skill去用在Jekyll上面。在過程中Claude可能會問你一些問題 比如說:
Q: 整體視覺風格方向？
A: 紙張感（米白、手寫風）
Q: 設計美感偏好？
A: 日式雜誌感（精緻排版）
Q: 這次想客製哪些部分？
A: Header/導航列, 文章頁閱讀體驗, 首頁文章列表排版, 整體色彩系統＋字型
A是我當時的回應
第一版就這樣跑出來了，然後再加上一些小玩意之後就完成了
怎麼可能這麼容易呢?
主題客製化的雷
第一個雷：網頁顯示原始碼亂碼
在資料夾裡點開 index.html，結果瀏覽器顯示的不是漂亮的網站，而是一堆亂碼
A：因為 Jekyll 網站不是點開來看的，而是需要打開一個本地伺服器來預覽
瀏覽器本身看不懂Jekyll的語法
必須在終端機（使用PowerShell）裡進入資料夾 輸入bundle exec jekyll serve啟動一台伺服器(需要Ruby)才能在http://localhost:4000裡面看到網頁
第二個雷：指令無效與依賴地獄
輸入bundle exec jekyll serve為什麼PowerShell還是給我一串錯誤?
A1:需要電腦有Ruby，確定安裝了bundle指令才可以用喔 A2:少了Gemfile
Jekyll在電腦上需要Gemfile才能順利的安裝(bundle install)
這個網頁需要的外掛功能
沒有Gemfile.bundle指令打進去是沒用的
因為沒有清單根本不知道需要裝什麼
A2-1:補上了Gemfile還是不行的話檢查看看裡面有沒有webrick和tzinfo-data
這兩個套件是Jekyll在Windows環境下必須的額外套件(因為系統層面上的差異)
如果沒有記得補進去Gemfile
# 解決 Windows 時區報錯的救星
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
# 讓 Ruby 3.0+ 版本的本地伺服器能正常運作
gem "webrick"
加上這兩行後，再執行一次 bundle install應該就可以了
第三個雷：本地端完美，上GitHub是另外一件事
我的網站在電腦上看是沒問題的為什麼放不上Github?
(部署顯示The github-pages gem can't satisfy your Gemfile's dependencies)
A:打開倉庫設定，修改GitHub預設機制的編譯權限
預設情況下，GitHub Pages 會使用名為"傳統模式（Deploy from a branch）"
來編譯網站。這個機制非常保守，它有一份嚴格的套件白名單
當它看到我們高度客製化網頁的Gemfile套件清單(不在白名單裡面的套件)
或是比較新的CSS語法的時候不會執行(因為都不在白名單里)。
所以呢，Settings -> 左側選單的 Pages,找到Build and deployment 區塊
把 Source 選項改為 GitHub Actions。
接著畫面會跳出推薦的Jekyll Workflow卡片，點擊Configure確認之後
按Commit儲存
修改之後推上去還是報錯誤(exit code 1)怎麼辦?
A:Gemfile,前面提過在Windows下Jekyll需要額外的東西才能運作
在bundle install指令裝好開啟本地的時候會產生一個Gemfile.Lock
這裡面記載的東西是在Windows環境裡面起動這個Jekyll的參數和額外套件的版本
在上傳的時候，負責執行的Actions伺服器會因為.Lock檔案和Linux環境對不上
而無法繼續 所以出現了exit code 1
解決方法?git rm Gemfile.lock把.Lock檔案從Github倉庫裡面移除
如果指令下去說找不到這個檔案怎麼辦?打開Jekyll資料夾把.lock檔案刪了再推一次
保險起見，請打開.gitignore 檔案，加上這句Gemfile.lock把檔案寫進黑名單
第四個雷：網址看起來沒錯，但點進去只有 404
部署上去一切安好，首頁也完美顯示。但喜悅只維持了三秒，因為我發現——只有首頁顯示。點擊導覽列的「關於我」、「標籤」或任何文章，全部都無情地跳出 404 找不到頁面。
Q：網址沒有問題，首頁的原始碼也有對應的地方，那怎麼還會這樣？
A：因為網站有「空殼（連結）」，卻沒有「實體（檔案）」！而且，你還可能不小心當了時空旅人。
這個 404 慘案，其實是由兩個隱蔽的坑聯手造成的：
兇手一：失蹤的實體頁面（空有衣架沒有衣服）客製化主題通常只會給你美麗的「版型（Layout）」。它在導覽列寫了「關於我」和「標籤」的按鈕，但它並不會自動幫你建立這些頁面。當 GitHub 照著網址（如 /about）去你的資料夾找人時，發現根本沒有 about.md 或 tags.html 這些實體檔案，自然只能兩手一攤給你 404。
解法： 手動在根目錄建立這些缺少的檔案（例如 about.md），並且在檔案最上方的 Front Matter 寫下 permalink: /about/，強制為它指定好網址歸屬地。
兇手二：來自未來的文章（Jekyll 的鐵則)
AI 幫我生成的範例文章，檔名日期竟然寫著 2026年
Jekyll 內部有一個規則：不顯示未來的文章
所以當 GitHub 伺服器（時間是現在）
看到這些 2026 年的文章時，會把它們當作隱形人
文章全部被隱藏了，依賴文章生成的「標籤頁」和「文章內頁」自然就抓不到東西
直接報錯 404。
解法： 乖乖把文章檔名的日期改回今天或過去
或者在 _config.yml 裡面加上一行 future: true，讓Jekyll允許時空旅行。
把這兩個坑填平最後一次 git push 後，看著所有連結終於都能順利打開
的成就感真的難以言喻
但是搬系統呢? Well.這又是另外一段故事了 我們下篇來講
