Cloudflare Pages#

サイト用リポジトリの CI では npm から空音 CLI を呼び出します。テンプレートは template/site/.github/workflows/pages.yml を参照してください。

# .github/workflows/pages.yml
- checkout サイト repo
- setup-node 23
- npx @sorane/cli validate --cwd . --json
- npx @sorane/cli index --cwd . --force   # 検索ページがある場合
- npx @sorane/cli build --cwd . --clean
- wrangler pages deploy dist --project-name <name>

初回のみ Cloudflare で Pages プロジェクトを作成してください。シークレットに CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を設定します。

空音公式サイト は空音リポジトリ内の website/ を dogfooding してビルドしています。ssg.sorane.dev でも同じサイトを表示します。

公式サイトの kototoi 埋め込みと掲示板は現在休止しています。CI は SSG のビルド成果物をそのまま公開し、問い合わせページでは GitHub Issues を案内しています。以前の埋め込み手順は kototoi 問い合わせフォーム に保存しています。

デプロイ前のプレビュー#

本番反映前にローカルで確認するには CLI の preview を使います。

npx @sorane/cli preview --cwd website --watch

draft: true の frontmatter を付けた記事はプレビューでのみ HTML 化され、Pages への通常 build では除外されます。

404 ページ#

ビルドは常に dist/404.html を出力します。Cloudflare Pages はこれを自動的にエラーページとして使います。

優先ソース結果
1content/404.mdsorane でレンダリング
2static/404.htmlそのままコピー
3なし言語に応じた既定ページ

404.md はサイトマップ・ブログ一覧・OKF バンドル・検索インデックスから除外されます。

リダイレクト（サイト移行）#

ビルドは Cloudflare Pages _redirects 形式の dist/_redirects を出力できます。Netlify 互換の静的ホストでも同じファイル名を読むことが多いです。

1. サイト設定で一括指定（sorane.yaml）:

build:
  redirects:
    - from: /2025-12-23-srn.html
      to: https://ssg.sorane.dev/2025-12-23-sorane-refactor.html
      status: 301

2. 記事 frontmatter で旧 URL を残す（HTML は出さず _redirects のみ）:

---
type: article
title: （移管済み）
redirect: https://ssg.sorane.dev/2025-12-23-sorane-refactor.html
redirect_status: 301
excludeFromList: true
profile: sorane-okf/0.2
---
項目挙動
frompermalink から決まる出力パス（/foo.html または foo.html）
to絶対 URL または同一サイト内パス（/new.html）
status301（既定）/ 302 / 303 / 307 / 308
出力redirect 付き記事は HTML・サイトマップ・feed・ブログ一覧から除外

static/_redirects に置いても 効きません（dist/static/ 配下になるため）。必ず空音の build.redirects か記事 redirect を使ってください。

図表（Mermaid）#

Mermaid は次の 2 モードがあります。

モードCI の追加要件ssg.sorane.dev
mermaid.mode: client（既定）なし（mermaid npm パッケージ）採用 — Pages ビルドに Chromium 不要
mermaid.mode: build@mermaid-js/mermaid-cli（mmdc）+ Chromium未使用 — 静的 SVG が必要なサイト向け

mermaid.mode: build を使うサイトは CI で Chromium を用意し、PUPPETEER_EXECUTABLE_PATH を設定してください。空音リポジトリの test.yml e2e ジョブは Playwright の Chromium を mmdc に流用してビルドテストしています。

大規模サイト#

記事やフォント資産が多いサイトは、コンテンツ用リポジトリを別にし、CI で npx @sorane/cli を pin してビルドします。

- checkout コンテンツ repo
- npx @sorane/cli index --cwd . --force
- npx @sorane/cli build --cwd . --clean
- wrangler pages deploy dist --project-name <name>

空音ソースを checkout する構成も可能です。AGENTS.md の SORANE_ROOT を参照してください。

検索#

FTS 検索はモデルを必要とせず、search-index.json を dist に含めます。

ドメイン構成#

ホスト用途
sorane.devプロダクトサイト（正規 URL、SSG 公式ドキュメント）
ssg.sorane.dev同じプロダクトサイトの追加ドメイン
sorane.pages.devPages 既定 URL

Pages プロジェクト sorane に両方のカスタムドメインを登録し、DNS の CNAME は sorane.pages.dev に向けます。website/sorane.yaml の base_url は https://sorane.dev とし、canonical・サイトマップ・機械可読出力の URL を統一します。

sorane.dev/* の Worker ルートは kototoi の割り当てを解除し、Pages に配信を任せます。kototoi の Worker と D1 データは保持しています。kototoi を再デプロイする際は、以前の設定でこのルートを再び割り当てないようにしてください。

アクセス解析・ログ（Cloudflare）#

空音は HTML にアナリティクス JS を埋め込みません。計測は Cloudflare ゾーン側で行います。

アクセス解析（無料プラン）#

Cloudflare には名前が似た製品が2つあります。ゾーンの HTTP Traffic で「Upgrade to Pro」が出るのは正常です（詳細な PV / Visits は Pro 以上）。

製品場所無料PV 相当空音 HTML
Pages Web AnalyticsWorkers & Pages → プロジェクト → Metrics → Enable○○（Core Web Vitals 含む）ビルド成果物に CF がスニペット注入（ソース Markdown には書かない）
ゾーン HTTP Trafficゾーン → Analytics & Logs → HTTP Traffic基本のみPro 以上で Page views / Visitsエッジ集計（JS 不要）

ssg.sorane.dev のような Pages サイト（解析だけ欲しい・監査不要）:

  1. 設定 で web_analytics: true（運用メモ用）
  2. Workers & Pages → sorane → Metrics → Web Analytics を Enable
  3. 次回デプロイ後に計測開始（数分〜24時間でデータ表示）

ゾーンの HTTP Traffic 無料枠（Requests / Bandwidth / Unique visitors）だけでも足りる場合は、Pro に上げずにそちらを見ても構いません。

Logpush（監査用アクセスログ・任意）#

公的サイトなどで HTTP リクエストの生ログが必要なときだけ、ゾーン Logpush（http_requests）→ R2 を設定します。

  1. sorane.yaml に logpush ブロックを追加
  2. templates/cloudflare/logpush/setup-r2.sh でジョブ作成

詳細: design/access-logs.md