Cloudflare Pages#

サイト用リポジトリの CI では npm から sorane を呼び出します。テンプレートは 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 を設定します。

sorane 公式サイト は sorane リポジトリ内の website/ を dogfooding してビルドしています。

問い合わせ（kototoi）を有効にしているサイトは、build のあとに埋め込み資産の配置と contact.html のパッチが必要です。手順は kototoi 問い合わせフォーム を参照してください。公式 CI（.github/workflows/pages.yml）では次を追加しています。

- run: node website/scripts/emit-kototoi.mjs
- run: node website/scripts/patch-contact.mjs

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

本番反映前にローカルで確認するには 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/ 配下になるため）。必ず sorane の build.redirects か記事 redirect を使ってください。

図表（D2 / Mermaid）#

build.diagrams.d2.enabled: true のサイトは CI で d2 CLI をインストールしてください。ssg.sorane.dev は v0.7.1 を使っています。

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 を設定してください。sorane リポジトリの 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>

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

検索・大容量資産#

  • 標準（FTS）: モデル不要。search-index.json のみ dist に含まれる
  • experimental（hybrid）: search.mode: hybrid + bundle_model: false で ONNX を R2 等から配信

ドメイン構成#

ホスト用途
ssg.sorane.devプロダクトサイト（SSG 公式ドキュメント）
sorane.dev空音掲示板（kototoi）— Pages プロジェクト sorane からは切り離す
sorane.pages.devPages 既定 URL

sorane.yaml の base_url を本番ホストに揃えてください。

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

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

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

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

製品場所無料PV 相当sorane 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