Blog — Jekyll + GitHub Pages 是做什麼的？

Repo: ~/repos/github.com/<you>/<you>.github.io Engine: Jekyll + GitHub Pages，主題：minima Branch: master — 推送後自動部署 Index: 維護一個部落格索引筆記檔案（例如 ~/notes/blog.md）— 每篇文章發布後更新

注意 — 不需要在本機進行 Jekyll 建置。GitHub 會在伺服器端建置。

⚠️ 嚴格規則：不得包含僱主資訊

絕對不能在文章中包含：

你僱主的內部工具、系統、代號或基礎設施
內部專案名稱、團隊名稱、組織結構或路線圖細節
客戶名稱、合作夥伴名稱或合約細節
內部工單、維基頁面或會議內容
薪資、員工人數、預算或業務指標

應撰寫關於 技術、工具和模式 的內容 — 而不是你在哪裡工作或你的僱主推出什麼產品。如有疑問，請在發布前詢問使用者。

工作流程

1. 撰寫文章

_posts/YYYY-MM-DD-slug-here.md

Frontmatter:

---
layout: post
title: "你的標題"
date: YYYY-MM-DD
categories: ai agents productivity   # 以空格分隔
series: "AI coding agent productivity"   # 若不屬於系列則省略
---

2. 風格

以問題開頭，而非解決方案
一個具體的開場句子 — 不要寫「在這篇文章中，我將...」
可執行的程式碼用程式碼區塊
比較用表格
結尾加上 ## Source 區塊，連結相關儲存庫或參考資料
不要有 LLM 廢話 — 像 README 一樣寫作
將 @word 轉義為 \@word，以避免未來可能需要 PDF 時的 typst 引用錯誤

挑選一篇部落格上評價良好的已發布文章，作為語氣和密度的參考。

3. 在發布前驗證每個連結（不可忽略此步驟）

憑記憶輸入的 URL 會產生 404。先用以下指令檢查每個連結的 HTTP 狀態：

for u in "https://example.com/a" "https://example.com/b"; do
  echo "$(curl -sS -L -o /dev/null -w '%{http_code}' "$u")  $u"
done

每個連結在提交前都必須回傳 200（或 301/302 指向有效目標）。這比發布後出現死連結、等到使用者發現再修正要划算得多。

4. 提交並推送

cd ~/repos/github.com/<you>/<you>.github.io
git add _posts/YYYY-MM-DD-slug.md
git commit -m "post: <title>"
git push   # GitHub Pages 會在大約 60 秒內自動部署

5. 更新索引

在部落格索引筆記檔案的 ## Posts 表格中新增一行（最新在最前面），如果文章屬於某個系列，則在 ## Active series 行中附加該文章：

| YYYY-MM-DD | Title | `category/path/YYYY/MM/DD/slug.html` |

URL 遵循 Jekyll 從 categories + date + slug 推導出的 permalink 模式。

6. 驗證文章是否確實上線（不可忽略此步驟）

成功的 Pages 建置並不表示文章已經上線 — Jekyll 會靜默地丟棄未來日期的文章。在建置完成後，用 curl 檢查真實的 URL：

base="https://<you>.github.io"; slug="/CATEGORY/PATH/YYYY/MM/DD/slug.html"
curl -sS -L -o /dev/null -w "%{http_code}\n" "$base$slug"   # 必須是 200
curl -sS -L "$base/" | grep -o 'slug[^"]*html' | head -1     # 必須出現在首頁

如果回傳 404 但建置成功，幾乎可以肯定就是下面提到的未來日期陷阱。

已發布文章的更新保護

保留原始敘述，並附加一個清楚標示的更新區塊，除非使用者明確要求改寫。
僅對新增或修改的 URL 進行 HTTP 檢查；除非被要求進行連結稽核，否則不要重複檢查未變更的已發布連結。
推送後，驗證真實的已發布 URL 回傳 HTTP 200。

提示

在部落格索引筆記檔案中保留一個 ## TODO 區塊，用來存放草稿點子；在從零開始撰寫前先檢查。
如果文章延續或反駁先前的文章，請使用 {% post_url YYYY-MM-DD-slug %} 連結它。
黎明前發布 + 未來日期陷阱： Jekyll 會將不包含時間的 date: YYYY-MM-DD 解釋為網站時區的午夜，並靜默丟棄日期在未來的文章。在 _config.yml 明確加入 timezone: 行之前，若文章在當地時間 04:00 撰寫，會被視為 UTC 午夜（約未來 1 小時）→ 被丟棄直到 UTC 時間追上。請在 _config.yml 中設定 timezone:，且不要移除它。如果黎明前的文章在建置成功後仍然 404，請在 frontmatter 中加上明確的時間（date: YYYY-MM-DD 04:00:00 +0530）。

Blog — Jekyll + GitHub Pages