静的サイト → GitHub Pages
完全なワークフロー:データ → 自己完結型HTML/CSS/JSページ → ブラウザ検証 → GitHub Pages公開。
対象:1〜数百アイテムのページ、単一作者、実行時の依存関係ゼロ。
使用するタイミング
| はい | いいえ |
|---|---|
| 「このリスト/テーブルでページを作って」「ギャラリー」「データダッシュボード」 | バックエンド、認証、データベースが必要なアプリ → 事前に相談 |
| 「GitHub / GitHub Pagesで公開して」 | フレームワーク(Next, Astro, Hugo)で生成されたサイト → フレームワークのフローに従う |
| 既存ページのデータ(タイトル、日付、価格…)の再現 | 第三者のデザイン/CSS/HTMLのコピー → 拒否し、独自デザインを提案 |
絶対ルール
- オリジナルデザイン。 第三者のCSS、HTML、アセットを決してコピーしない。情報構造にインスパイアされるのはOK。デザインを流用するのはNG。
- 事実はOK、著作物はNG。 タイトル、日付、価格、評価、リンク = 事実データ、再利用可能。編集テキスト、説明文、ビジュアル = 保護対象:コピーしない。画像は、コミットする代わりに元のCDNにホットリンクする(
reference/data-and-ethics.md参照)。 - アクセス制限を尊重する。
robots.txtでクローラー禁止、Cloudflare/botチャレンジ → 迂回しない。公式API、キー、または単なる外部リンクにフォールバックする。 - 「完了」と言う前に必ず実ブラウザで検証(スクリーンショット+クリックテスト)。
- リポジトリ名/アカウントが曖昧な場合は確認なしに公開しない。
- 確認なしにカスタムドメインを作成しない。 ユーザーが指定していない場合は、Cloudflareリダイレクトを希望するかどうか、どのドメインかを尋ねる(ステップ6)。サブドメインを勝手に作ったり、独自に作成したりしない:DNSは外部に見える副作用である。
ワークフロー
1. フレーミング(30秒)
-
どんなデータか、アイテム数、1回限りか定期的な更新か?
-
期待される出力:1ページ?ソート/検索?どのようなビジネス表示ルールか?
-
公開先:GitHubアカウント、リポジトリ名、公開/非公開(Pagesは無料アカウントでは公開リポジトリが必要)。
-
カスタムドメイン — 指定がない場合は明示的に尋ねる。 一度に質問し、デフォルトの提案を含める:
Cloudflareリダイレクトを
<owner>.github.io(CNAME、プロキシ無効)に設定しますか? はいの場合、どのサブドメイン/セクションですか?スキル側では名前は自由ですが、ドメインは作成された瞬間から公開されます:明示的な回答なしには何も作成しない。ユーザーが「いいえ」と答えた場合は、URL
https://<owner>.github.io/<repo>/で終了し、DNSエントリは作成しない。
2. データ取得
1回のスクリプト実行 → 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
Chromeヘッドレスでページを開き、/tmp/site-shot.pngに書き込み、クリック重なりテストを実行する。スクリーンショットを確認(read_imageツール)してから結論を出す。
チェックリスト:デスクトップ+モバイルレンダリング、データ完全(アイテム数をカウント)、リンク正しい、重なりなし。
5. 公開
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site マイレポ名
スクリプト: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が先、証明書が次、Enforce HTTPSが最後。 サイトはすでに *.github.io で200を返している必要がある。
a. CloudflareでのDNSリダイレクト(MCP Cloudflare)
前提トークン:スコープ zone.read + dns.write(Zone Read / DNS Edit)。不足している場合は、停止して拡張を依頼する — 迂回しない。
GET /zones?name=<ルートドメイン>→zone.id。ゾーンが0の場合:そのドメインはこのアカウントにない、確認する。GET /zones/{zone_id}/dns_records?name=<FQDN>→ 同じCNAMEが既に存在する場合は、何も再作成しない(冪等性)。POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<サブドメイン>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= DNS only、譲歩不可:CloudflareプロキシはGitHubが証明書を発行するのを妨げる。- ターゲットは
<owner>.github.io、末尾スラッシュなし、リポジトリ名なし(jamesdadams.github.io、.../mon-repoではない)。 ttl: 1= Auto。
- APIだけでなく、公開解決で確認:
dig +short <fqdn> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1 # → 185.199.108-111 .153
b. GitHub Pages側のドメイン+Enforce HTTPS
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <ドメイン> ./site
スクリプト:サイトに CNAME ファイルを書き込み(再デプロイ後も持続し、ドメイン消失を防止)→ PUT /repos/{owner}/{repo}/pages を cname で実行 → https_certificate.state = approved を待機 → https_enforced: true を有効化。
⚠️ https_enforced: true は、証明書が存在するまで400を返す。実際の遅延:CNAME作成後5〜20分。そのためスクリプトは失敗せずにループする。発行前に手動で「Enforce HTTPS」にチェックを入れないこと、そしてこの期間中に失敗と結論づけないこと。
c. 最終確認
curl -sI https://<ドメイン>/ | head -5 # 200 + ヘッダー server: GitHub.com
次に、ブラウザでページを再度開く(ステップ4)カスタムURLで:200は、相対パス(styles.css、script.js)が解決することを保証しない — これがドメインルートで提供されるプロジェクトページの典型的な落とし穴である。
7. 更新を可能にする
- Gitフォルダをユーザーのプロジェクトフォルダに配置する(
/tmpでは再起動で消去される)。 README.mdに文書化:データの出典、抽出の再実行方法、固定データと動的データ(JSで計算されるルール)の区別。- 自動更新されないことをユーザーに明示的に伝える。
既知の落とし穴
| 症状 | 原因 | 修正 |
|---|---|---|
| 403「Just a moment…」 | Cloudflareチャレンジ | 制限を文書化、公式APIか外部リンク;迂回を試みない |
| 「Making sure you're not a bot」でページが切り詰められる | PoW Anubis | チャレンジを解決(reference参照)か、ユーザーにエクスポートを依頼 |
| セレクタが全アイテムに対して0件を返す | 間違ったパターン(例:/games/lib/genre: vs /games/lib/popular/genre:) | HTMLのサンプルを出力し、ループ前に1ページで正規表現をテスト |
| カードクリックで正しいリンクが開かない | <a>レイヤーが子要素のpositionで覆われている | 装飾要素に 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分後もカスタムドメインが404 | CNAMEがない/所有者が間違っている/リポジトリに CNAME ファイルがない | digでCNAMEを確認、set-pages-domain.shを再実行 |
| プロキシ有効化後にHTTPSが壊れる | レコードがProxiedになっている | DNS only(proxied: false)に戻す、GitHub証明書はプロキシ経由では検証できない |
| 「Domain is already in use」 | そのドメインがすでにアカウント内の別のリポジトリで宣言されている | カスタムドメインはリポジトリごとに1つ;再割り当て前に古い方を解放 |
カスタムドメインでCSS/JSが404だが *.github.io/repo/ ではOK | 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— カスタムドメイン+Enforce HTTPS(Cloudflare CNAME後)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}