Community程式設計與開發github.com

static-site-publish

從資料(清單、圖庫、儀表板、作品集)生成純 HTML/CSS/JS 靜態網站,在無頭瀏覽器中驗證,然後發佈到 GitHub Pages 並設定自訂網域與 Cloudflare 重新導向。

static-site-publish 是什麼?

這個技能提供了一個完整的工作流程:將結構化資料(例如清單、表格、圖庫或儀表板)自動轉換為一個自包含的靜態網站(僅使用 HTML/CSS/JS,無需建置工具或框架),然後在 headless Chrome 中驗證其渲染正確性,最後將網站發佈到 GitHub Pages。它還支援自訂網域設定,包括透過 Cloudflare API 建立 CNAME 記錄(proxy 停用)並在 GitHub Pages 啟用強制 HTTPS。 此技能目的在於處理單一作者、數百個項目以內的資料頁面,零執行期依賴。它強制遵守原創設計(禁止複製第三方 CSS/HTML/素材)、資料倫理(尊重 robots.txt 與存取保護)、並要求使用者在建立 DNS 記錄前明確確認自訂網域。工作流程包含七個步驟:範圍界定、資料擷取、頁面生成、瀏覽器驗證、發佈、自訂網域設定與 Cloudflare DNS 配置、以及確保後續可更新性。 支援平台:在任何支援 CLI(Python、Bash、Git、GitHub CLI、dig)的環境中執行(例如 Claude Code、Codex、Cursor)。技能提供範本與腳本來自動化大部分流程,但要求使用者在關鍵步驟(資料來源、倉庫名稱、自訂網域)提供明確輸入。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

靜態網站 → GitHub Pages

完整工作流程:資料 → 自包含 HTML/CSS/JS 頁面 → 瀏覽器驗證 → 發佈至 GitHub Pages。

適用範圍:1 到數百個項目的頁面、單一作者、零執行期依賴。

何時使用

是否
「幫我做一個有這份清單/表格的頁面」、圖庫、資料儀表板需要後端、驗證、資料庫的應用程式 → 先詢問
「把它發佈到 GitHub/GitHub Pages」由框架(Next、Astro、Hugo)產生的網站 → 遵循框架流程
以資料形式重現現有頁面(標題、日期、價格…)複製第三方網站的設計/CSS/HTML → 拒絕,重新設計一個乾淨的版面

不可協商的規則

  1. 自行設計。 絕不複製第三方網站的 CSS、HTML 或素材。可以參考資訊結構;但不能沿用其視覺風格。
  2. 事實可以,作品不行。 標題、日期、價格、評分、連結 = 可重複使用的事實資料。編輯性文字、描述、視覺內容 = 受保護:請勿複製。對於圖片,直接連結原始 CDN 而非提交到倉庫(參閱 reference/data-and-ethics.md)。
  3. 尊重存取保護。 robots.txt 禁止爬蟲、Cloudflare/bot 驗證挑戰 → 不得繞過。應尋找官方 API、金鑰,或退化為單純的外部連結。
  4. 務必在真實瀏覽器中驗證(截圖 + 點擊測試)才能說「完成了」。
  5. 在倉庫名稱或帳號不明確時,務必先確認再發佈。
  6. 未經確認,不得建立自訂網域。 如果使用者未指定,詢問他是否要設定 Cloudflare 重新導向以及網域名稱(步驟 6)。絕不能自行臆測子網域或建立任何內容:DNS 是外部可見的副作用。

工作流程

1. 範圍界定 (30 秒)

  • 什麼資料、多少項目、一次性更新還是定期更新?

  • 預期輸出:一個頁面?排序/搜尋?哪些業務顯示規則?

  • 發佈位置:GitHub 帳號、倉庫名稱、公開/私人(免費帳戶的 Pages 要求公開倉庫)。

  • 自訂網域 — 若未指定,需明確詢問。 一次提出問題,並附上預設建議:

    你想要 Cloudflare 重新導向到 <owner>.github.io(CNAME,proxy 停用)嗎?如果是,請提供子網域/路徑。

    技能端名稱可自行決定,但網域一經建立即為公開:在沒有明確回應前不得建立任何內容。如果使用者回答「否」,就停留在 https://<owner>.github.io/<repo>/ 網址,不建立 DNS 記錄。

2. 取得資料

僅一次腳本執行 → 一個 data.json = 單一事實來源,與渲染分離。

python3 fetch_data.py     # → data.json

禮儀:請求間隔 0.3–0.7 秒、明確的 User-Agent、遇到 429/5xx 時重試。 詳情與陷阱(PoW Anubis、Cloudflare、模糊比對、無金鑰 API):參閱 reference/data-and-ethics.md。

3. 生成頁面

從範本開始,不要從零開始:

cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/   # data.json → index.html
python3 ./site/build.py
  • build.py:小型 Python 生成器(使用 f-string + html.escape),將資料注入卡片網格。資料部分無需 JS 執行期。
  • styles.css:預設深色主題、auto-fill minmax() 網格、CSS 變數。
  • script.js:即時搜尋 + 排序 + 在開啟時計算顯示規則(使頁面無需重建即可保持正確)。
  • 所有可在顯示時計算的內容(狀態、相對日期)都應由 JS 處理:這樣就不需要每天重建網站。
  • HTML 應在無 JS 時仍可讀,且 JS 應是漸進增強。

4. 驗證

.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html

在 headless Chrome 中開啟頁面,寫入 /tmp/site-shot.png,並執行點擊重疊測試。查看截圖(使用 read_image 工具)後再下結論。 檢查清單:桌面 + 行動裝置渲染、資料完整(計算項目數量)、連結正確、無重疊。

5. 發佈

.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site my-repo-name

腳本內容:gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → 輪詢 URL 直到回傳 200 → 顯示最終 URL。

Pages 的延遲為 20 到 90 秒:在成功回傳 200 之前,不要斷定「它沒成功」。也要檢查 gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built。

6. 自訂網域 + Cloudflare

僅在使用者要求時才執行(參閱步驟 1)。DNS 是公開的:不要將模糊的「好」自行解讀為 AI 選擇的網域名稱。

強制順序:先 DNS、再憑證、最後啟用強制 HTTPS。 網站必須已在 *.github.io 上回傳 200 才能開始。

a. 在 Cloudflare 設定 DNS 重新導向(MCP Cloudflare)

必要權杖:範圍 zone.read + dns.write(Zone Read / DNS Edit)。如果缺少,停止執行並要求擴大權限 — 不得繞過。

  1. GET /zones?name=<根網域> → zone.id。如果回傳零個區域:該網域不在這個帳號中,請詢問。
  2. GET /zones/{zone_id}/dns_records?name=<完整網域名> → 如果已存在相同的 CNAME,則不建立任何記錄(冪等性)。
  3. POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<子網域>", "content": "<owner>.github.io",
  "proxied": false, "ttl": 1 }
  • proxied: false = 僅 DNS,不可協商:Cloudflare proxy 會阻止 GitHub 簽發憑證。
  • 目標是 <owner>.github.io,結尾無斜線且不含倉庫名稱(例如 jamesdadams.github.io,不是 .../my-repo)。
  • ttl: 1 = 自動。
  1. 透過公開解析驗證,而不僅是透過 API:
dig +short <完整網域名> CNAME @1.1.1.1   # → <owner>.github.io.
dig +short <完整網域名> A @1.1.1.1       # → 185.199.108-111 .153

b. 在 GitHub Pages 端設定網域 + 強制 HTTPS

.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domain> ./site

腳本內容:在網站中寫入 CNAME 檔案(它會存活於重新部署,避免遺失網域)→ PUT /repos/{owner}/{repo}/pages 並帶有 cname → 等待 https_certificate.state = approved → 啟用 https_enforced: true。

⚠️ https_enforced: true 在憑證不存在時會回傳 400。實際延遲:建立 CNAME 後 5 到 20 分鐘。因此腳本會輪詢而非直接失敗。在憑證簽發前,不要手動勾選「強制 HTTPS」,也不要在這段期間內斷定失敗。

c. 最終驗證

curl -sI https://<domain>/ | head -5      # 200 + header server: GitHub.com

然後在瀏覽器中重新打開頁面(步驟 4)使用自訂網域 URL:回傳 200 並不保證相對路徑(styles.css、script.js)能正確解析 — 這是提供給根網域的 project page 的經典陷阱。

7. 使後續更新成為可能

  • 將 git 資料夾放在使用者的專案資料夾中(不要放在 /tmp,重開機後會被清除)。
  • 在 README.md 中記錄:資料來源、如何重新執行提取、哪些是固定的(資料)vs 動態的(由 JS 計算的規則)。
  • 明確告知使用者哪些項目不會自動更新。

已遇過的陷阱

症狀原因修正
403「Just a moment…」Cloudflare 驗證挑戰記錄限制、尋找官方 API 或提供外部連結;不要嘗試繞過
頁面截斷「Making sure you're not a bot」PoW Anubis解決挑戰(參閱 reference)或要求使用者匯出資料
選擇器對所有項目回傳 0 結果錯誤的模式(例如 /games/lib/genre: 而非 /games/lib/popular/genre:)印出 HTML 樣本並在 1 個頁面上測試正規表示式,再進行迴圈
點擊卡片卻未開啟正確連結<a> 層被定位的子元素覆蓋在裝飾性元素上設定 pointer-events: none;使用 elementFromPoint 測試
GitHub Pages 前幾分鐘回傳 404正在建立輪詢直到 90 秒
某一欄資料為空來源端的標籤可變(例如「Released」vs「Early Access」)使用容錯模式 + 逐項目記錄,絕不能使用無聲的 except: pass
https_enforced 回傳 400「certificate does not exist」憑證尚未簽發等待 https_certificate.state = approved(5-20 分鐘),腳本會輪詢
自訂網域 30 分鐘後仍 404CNAME 缺失/錯誤的所有者/倉庫中缺少 CNAME 檔案使用 dig 確認 CNAME,重新執行 set-pages-domain.sh
啟用 proxy 後 HTTPS 損壞記錄被設定為 Proxied改回 DNS only(proxied: false),GitHub 憑證無法透過 proxy 驗證
「Domain is already in use」網域已在同一個帳號的其他倉庫中使用每個倉庫一個自訂網域;先釋放舊的才能重新指派
CSS/JS 在自訂網域回傳 404,但在 *.github.io/repo/ 正常在提供給根網域的 project page 上使用了絕對路徑(/styles.css)使用相對路徑(styles.css)

參考資料

  • reference/data-and-ethics.md — 資料提取、PoW Anubis、Cloudflare、授權、圖片熱連結
  • reference/design-and-verify.md — 最小設計系統、瀏覽器測試、無障礙
  • reference/publish-gh-pages.md — gh 指令、命名、網域、疑難排解
  • scripts/publish-gh-pages.sh — 發佈 + 啟用 Pages
  • scripts/set-pages-domain.sh — 自訂網域 + 強制 HTTPS(在 Cloudflare CNAME 之後)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

相關技能