SvelteKit Blog Engine v1.0.0.10 バージョンのアップデート内容をご案内します。

多言語での記事投稿が増えるにつれて、管理画面で特定の言語の記事だけを絞り込んで確認したり、翻訳が未作成の言語状況を把握することが難しくなっていました。今回のバージョンでは、この点を解消する記事管理ページの動的言語タブ機能の追加、ブログHub（hub.sveltekitblog.com）連携プロトコルの改善、エディタ書式消失防止ガード、デプロイコマンドの簡素化を実施しました。

1. 記事管理ページの言語別フィルタータブ機能

従来はすべての記事が作成日順に一括表示されていたため、韓国語・英語・日本語などが混在している場合の管理が煩雑でした。

主な改善点

• 動的な言語検出とカウントバッジ: 言語一覧をコードで固定せず、データベースに登録された言語と実際の記事データを総合してタブを動的に生成します。各タブの横にはリアルタイムで記事数が表示されます（例：[全体 (24)], [韓国語 (10)], [English (8)], [日本語 (6)]）。
• 記事未作成の言語選択時の案内: まだ記事が0件の言語タブ（例：English (0)）を選択した際、単に空のテーブルを表示するのではなく、親切な案内文とともに[+ この言語で新規作成]ボタンを表示し、スムーズな執筆動線を確保しました。
• 単一言語環境への配慮: 多言語を使用せず1言語のみで運用しているブログでは、不要なタブバーを非表示にしてシンプルな画面を維持します。
• 記事一覧の言語チップと言語切替時リセット: テーブルの各タイトル横に言語コード（KR, EN, JAなど）を表示して一目で識別できるようにし、タブ切替時には自動で1ページ目にリセットされるよう処理しました。

2. ブログHub（hub.sveltekitblog.com）連携プロトコルの改善

中央フィードプラットフォームであるSvelteKit Blog Hubへの記事送信時に発生していたエッジケースを整理・改善しました。

主な修正内容

• 導入文1,500文字の標準HTML自動抽出: Markdown形式やHTML形式を問わず、フィードカードに適した1,000〜1,500文字の標準HTML導入文をサーバー側で安全に抽出して送信します。
• 画像相対パスの絶対URL自動変換: 本文内の/images/posts/...などの相対パス画像を、代表ドメインを含む完全な絶対URL（https://ドメイン/images/...）に自動変換し、Hubフィードで画像が正常に表示されるようにしました。
• 記事更新時の初回公開日保持: 既存記事を編集・更新した際、更新日時で上書きされず、初回公開日（published_at）を保持してHubタイムラインの時系列順序が崩れないようにしました。
• Hub自動送信のデフォルト有効化設定: 管理設定（⚙️ 設定）に「記事作成時のHub自動送信デフォルト有効化」トグルを追加し、新規作成時に毎回チェックボックスを押す手間を省けるようにしました。

3. エディタ書式消失防止ガード

エディタのモード切替やタイプ変更時に、作成中の内容が誤って失われないよう安全装置を追加しました。

• HTML ➔ Visualモード切替警告: HTMLエディタでカスタムテーブルやインラインスタイルを記述した後にVisualモードへ戻ると、パーサーによって非標準タグが自動整形され削除される場合があります。これを防ぐため、切替前に確認ダイアログを表示するようにしました。
• エディタ種別（HTML ↔ Markdown）のロック: すでに保存された記事についてはデータ保護のためエディタ種別をロックし、変更を試みた際に警告メッセージでデータ損失を事前に認知できるようにしました。

4. マルチアカウントデプロイ（deploy-multi）CLIオプションの簡素化

複数インスタンスを管理するdeploy-multiスクリプトの引数入力をより直感的に改善しました。

# 従来の指定方法
npm run deploy:multi -- myaccount --admin-only

# 新しい簡素化フォーマット
npm run deploy:multi -- myaccount admin   # 管理画面のみ高速デプロイ
npm run deploy:multi -- myaccount blog    # ブログ側のみ高速デプロイ
npm run deploy:multi -- myaccount         # 両方（ブログ＋管理画面）を一括デプロイ

(従来の--admin-onlyや--blog-onlyフラグも100%下位互換性を維持しています。)

アップデート適用方法

最新のリポジトリコードを取得した上で、デプロイコマンドを実行してください。

# 最新コードの取得
git pull origin main

# デプロイ実行（例）
npm run deploy:admin
# マルチアカウントデプロイの場合
npm run deploy:multi -- <アカウント名> admin

実際のブログ運用を通じて、今後も使いやすさと安定性の向上に努めてまいります。ご意見やご要望がございましたらお気軽にお寄せください。

スタンドアロンの個人ブログを運営する際、最大の課題は**「どのようにして新しい読者に記事を届けるか」**です。商用プラットフォームとは異なり、自作ブログはデータやデザインの完全な自由を享受できますが、初期のアクセス流入や検索エンジンへの露出には多くの時間と労力が必要となります。

**SvelteKitブログ統合ハブ（hub.sveltekitblog.com）**は、独立ブログが抱える発見性（ディスカバリー）の限界を克服し、ブロガー同士がトラフィックと統計を共有しながら共に成長できるよう設計された分散型フェデレーション・フィードプラットフォームです。

本ガイドでは、API Keyの発行からブログ管理画面での設定、記事の作成・更新・削除ライフサイクル、そしてGoogle AdSenseとの相乗効果まで、ハブ連携の全手順を分かりやすく解説します。

1. 🎯 ハブ連携のコア機能と仕組み

1. データの完全な独立性と所有権:
   • 記事の本文元データや全DBレコードは、自身のCloudflare D1に安全に保管されます。
   • ハブにはカード表示に必要な**標準HTML導入文（1,000〜1,500文字）**とメタデータ（タイトル、サムネイル、スラッグなど）のみが安全に送信されます。
2. 画像の絶対URL自動変換:
   • MarkdownやHTML内の相対パス画像（/images/...）は、自身のドメインを含む絶対URL（https://...）に自動変換され、ハブフィード上でリンク切れなく美しく表示されます。
3. 非同期ノンブロッキング（Non-blocking）耐障害設計:
   • ハブサーバー側でネットワーク遅延や一時的な障害が発生しても、自身のブログの記事保存トランザクションは100%正常に完了するよう安全に保護されています。

2. 🔑 ステップ1：ハブAPI Keyの発行とブログ設定

① ハブプラットフォームでAPI Keyを発行

1. **SvelteKitブログハブの「ブログ連携（API発行）」**にアクセスします。
2. 自身のブログ代表URL（例：https://myblog.com）を登録し、発行された固有のSite API Key（sk_board_... または sk_hub_...）をコピーします。

② ブログ管理画面（⚙️ 設定）への登録

1. ブログ管理画面にログインし、[設定] メニューを開きます。
2. SvelteKitブログハブ（Hub）連携設定 セクションを確認します。
   

[ SvelteKitブログハブ(Hub)連携設定 ]
* ハブプラットフォームURL : https://hub.sveltekitblog.com（固定）
* ハブ発行 API Key : sk_hub_live_...（発行されたKeyを入力）
* 🌐 記事作成時のハブ同時配信デフォルト有効化 : [ON / OFF トグル]

3. 記事作成時のハブ同時配信デフォルト有効化をONにしておくと、新規記事作成時に自動で連携チェックが入るようになります。
4. 画面下の [設定を保存] ボタンをクリックして完了します。

3. ✍️ ステップ2：投稿エディタでのハブ同時配信

記事作成・編集画面（新規投稿 または 投稿編集）のメタデータサイドバー下部に、ハブ自動送信チェックボックスが用意されています。

[☑️] 🌐 SvelteKitブログハブ（hub.sveltekitblog.com）へ自動送信
     チェックを入れると、記事公開時にハブフィードへ要約カードが自動配信されます。
     チェックを外すとフィード上で「非表示」となり、読者のいいね（推薦）統計は安全に保持されます。
     ハブから完全に削除するには、ブログ側で記事を削除してください。

• 公開記事の保存（Status: Published）:
  • チェックが入った状態で保存すると、D1 DBへの保存と同時にハブへHTML導入文とサムネイルが送信され、ハブフィードに即時公開されます。
• 下書き保存（Status: Draft）:
  • 下書き状態の記事は、チェックが入っていてもハブフィードに公開されることはありません。

4. 🔄 ステップ3：記事更新・URL変更・非公開・削除ライフサイクル

ブログ運営中に行われる記事の加筆修正、カテゴリ変更、非公開化、削除などの操作は、エンジンが自動検知してハブと完全に同期します。

5. 💰 Google AdSense審査対策と相乗効果

ハブ連携を通じて獲得できる読者トラフィックは、Google AdSenseの審査通過および収益化に極めて有利に働きます。

1. 初期アクティブトラフィックの確保:
   • Googleのクローラーは、訪問者がゼロのサイトよりも実際のアクティブユーザーが流入しているブログを優先的かつ高評価でインデックスします。
2. ads.txt の完全自動配信:
   • 管理画面の ads_txt 入力欄にAdSense承認コード（google.com, pub-..., DIRECT, f08c47fec0942fa0）を入力しておくだけで、https://自身のドメイン.com/ads.txt として即時配信されます。
3. コンテンツ品質ガイドライン:
   • AdSense初回審査通過のため、1,500文字以上の良質な技術・情報記事を15〜20本以上ハブと連携して継続的に投稿することをお勧めします。

6. 🏁 おわりに

SvelteKitブログハブ連携を活用し、自身の独立ブログが持つデータ主権を完全に守りながら、より多くの読者と繋がる強力なシナジーを体験してください！

GitHub リポジトリに新しいリリースバージョンが公開された際、最新コードを取得してブログに反映する中で、次のような慎重な疑問が生じることがあります。

「新バージョンのエンジンコアやデータベースマイグレーションは、現在稼働中の本番ブログへ問題なく適用できるだろうか？」

SvelteKit Blog Engine では、レイアウト、カラー、フォントなどのデザイン設定や投稿記事がすべて D1 データベースに安全に保持されるため、コードを更新しても管理画面で設定したブログ UI が初期化されることはありません。

しかし、新バージョンで追加されたコア機能や D1 スキーマ変更、デプロイスクリプトが自身の Cloudflare 環境で正常に動作するかを事前に確認したい場合があります。その際、最も安全な方法は無料の Cloudflare 補助アカウント（テストインスタンス）へ先にデプロイして動作を確認し、問題がなければ本番アカウントへ反映することです。

従来の Cloudflare ツール（Wrangler）では、アカウント切り替えのたびにブラウザログインのやり直しや設定ファイルの書き換えが必要で、ローカルキャッシュの競合による誤デプロイのリスクもありました。本記事では、そのような手間を排除し、**新リリースをテスト環境で事前検証して本番へ安全にデプロイする「複数アカウント対応ワンクリックデプロイパイプライン」**をまとめました。

🔄 1. 実践的な安全デプロイワークフロー

複数アカウントデプロイシステムを活用することで、以下のような安全なデプロイサイクルを構築できます。

🔑 2. 事前準備：Cloudflare API トークンの発行（アカウント毎に初回1回）

ブラウザポップアップなしでバックグラウンドから安全にデプロイするため、各 Cloudflare アカウントで API トークン を初回1回のみ発行しておきます。

2-1. 最小権限 API トークンの作成手順

1. Cloudflare ダッシュボード ログイン ➔ 右上 [マイプロファイル] ➔ [API トークン] メニューへ移動。
2. [トークンを作成] をクリックし、Cloudflare Pages を編集 テンプレートの [テンプレートを使用] を選択。
3. アクセス許可（Permissions） セクション下部の + さらに追加 を押し、以下の2つの権限を追加します：
   • アカウント - D1 - 編集 (D1 データベーススキーマ自動マイグレーション用)
   • アカウント - Workers KV Storage - 編集 (画像保存用バインディング)

💡 セキュリティ Tip: グローバル API キーの代わりに、ビルド・デプロイに必要な Pages、D1、KV の3リソースのみ権限を付与する方式（最小権限の原則） が最も安全です。

4. アカウントリソース で対象アカウントを選択し、[概要へ進む] ➔ [トークンを作成] をクリック。
5. 発行された API トークン文字列 をコピーします。

2-2. 32桁のアカウント ID の確認

ダッシュボード接続時のブラウザアドレスバー(URL)から32桁の文字列を確認できます：

https://dash.cloudflare.com/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/workers-and-pages
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                             (この部分が Account ID です)

📦 3. バックアップファイルによる1秒アカウント登録 (deploy:sync)

D1 ID や KV ID を手動で探す必要なく、管理画面の基本機能である「デプロイ設定バックアップ」ファイルを利用して一括登録します。

1. 対象ブログの管理画面 ➔ [環境設定] ➔ [データ管理] から [デプロイ設定ダウンロード] をクリック。
2. ダウンロードしたファイル名を任意のアカウント識別子に変更し、プロジェクトルートへ配置：
   • 例（テストアカウント）：wrangler.backup.test.json
   • 例（本番アカウント）：wrangler.backup.main.json
3. ターミナルで同期コマンドを実行：

npm run deploy:sync

======================================================
✅ [.deploy-accounts.json] アカウント設定の同期完了！
======================================================
📋 [登録済みアカウント一覧]
  - main (Main Blog Account): 🟢 準備完了
  - test (Test Blog Account): 🟡 token/accountId の入力が必要です

4. 生成された .deploy-accounts.json を開き、発行した token と accountId を入力します：

{
  "test": {
    "name": "Test Staging Account",
    "token": "実際のAPIトークン",
    "accountId": "実際の32桁アカウントID",
    "blogProject": "test-blog-web",
    "adminProject": "test-blog-admin",
    "d1": {
      "BLOG_DB": { "name": "test-blog-db", "id": "11111111-2222-3333-4444-555555555555" },
      "USER_DB": { "name": "test-user-db", "id": "66666666-7777-8888-9999-000000000000" }
    },
    "kv": {
      "IMAGES_KV": "aaaaaaaaaabbbbbbbbbbccccccccccdd"
    }
  }
}

安全性の保証: deploy:sync は入力済みのトークンやアカウント ID を上書きせず安全に保持(Merge)します。

🚀 4. 実践デプロイシナリオ

シナリオ A. テストアカウントへの先行検証デプロイ（推奨）

npm run deploy:multi -- test

シナリオ B. 検証完了後の本番アカウント安全デプロイ

npm run deploy:multi -- main

シナリオ C. 複数ブログの一括バージョンアップ

npm run deploy:multi -- --all

シナリオ D. ブログ画面または管理画面の個別選択デプロイ

# test アカウントの Blog(Web) のみデプロイ
npm run deploy:multi -- test --blog-only

# test アカウントの Admin(管理画面) のみデプロイ
npm run deploy:multi -- test --admin-only

🛡️ 5. セッション競合を遮断する3段階サンドボックス設計

1. セッションサンドボックス: APPDATA を一時ディレクトリへ隔離し、ローカル PC の既存ブラウザログインセッションを保護します。
2. アトミックな設定復元: デプロイの瞬間のみ対象の wrangler.json を適用し、完了後に finally ブロックで確実に元通り復元します。
3. キャッシュ自動削除: デプロイ直後にローカルキャッシュを初期化するため、通常の単一デプロイコマンド（npm run deploy:blog 等）と併用してもセッションが混ざりません。

📋 6. コマンドリファレンスまとめ

💡 7. おわりに

管理画面でカスタマイズしたデザインや記事データは D1 データベースにそのまま保持された状態で、テスト環境を通じて安心して新リリースを反映できるデプロイパイプラインが整いました。

安全な複数アカウントデプロイを活用し、ご自身のブログをより安定的かつ快適に運用してください。

v1.0.0.8に続き、今回の v1.0.0.9 リリースでは、複数アカウント対応ワンクリック Cloudflare Pages 統合デプロイ、SvelteKit Blog Hub BLOG FEED 連携、Google AdSense 審査承認に向けた SEO/サイトマップ全面最適化および RSS/サイトマップのデザイン統一、そして 多言語(i18n)辞書の完成度向上とデプロイ同期の利便性改善 が導入されました。

1. 🌐 複数アカウントのスマート自動同期およびワンクリック Cloudflare Pages デプロイ

• wrangler.backup.json によるスマート自動同期 (npm run deploy:sync):
  • 管理画面からダウンロードしたバックアップファイル(wrangler.backup*.json)をルートフォルダに配置して同期コマンドを実行するだけで、D1 ID、KV ID、プロジェクト名を自動検出し、.deploy-accounts.json に完全登録します。
  • ユーザーが入力済みの API トークンとアカウント ID は 100% 安全に保持(Merge)されます。
• ワンクリック複数アカウントデプロイランナー (npm run deploy:multi):
  • npm run deploy:multi -- <アカウントキー> コマンド一発で、指定アカウントの Blog + Admin (2つの CFP) を連続自動デプロイします。
  • --blog-only、--admin-only の個別選択デプロイおよび登録済み全アカウントの一括デプロイ(--all)に対応。
• 完全なキャッシュサンドボックス分離と自動クリーンアップ:
  • APPDATA: .wrangler-multi-temp 一時フォルダにより、グローバルな Wrangler セッションを 100% 隔離します。
  • デプロイの瞬間のみ wrangler.json をインメモリスワップし、デプロイ完了後に finally ブロックで元の設定ファイルへ 100% 復元します。
  • デプロイ直後にローカルの .wrangler およびキャッシュを自動削除し、通常の単一デプロイ(deploy:admin、deploy:blog)への影響を 0% に保ちます。
• D1 ス키마自動マイグレーション (sync-secrets.js):
  • デプロイパイプライン内で D1 DB に is_syndicated カラムを安全に自動追加します。

2. 📡 SvelteKit ブログハブ(Hub) 統合フィード連携

• リアルタイムハブクライアントモジュール (hub.ts, syndication.ts):
  • 記事公開時に SvelteKit Blog Hub BLOG FEED へ記事のメタデータカードをリアルタイム送信する連携パイプラインを構築しました。
• 管理画面エディタのハブ連携トグル UI (PostMetadataForm.svelte):
  • 記事の作成・編集時にハブへのフィード送信フラグ(is_syndicated)をワンクリックで切り替えられるトグルチェックボックスを追加しました。
• DB ス키마拡張 (schema-blog-db.sql):

• カテゴリーウィジェットの一本化: 設定の混乱を招いていた従来の category_link オプションを完全撤廃し、単一の**「カテゴリーメニュー」ウィジェット**に統合。
• 投稿数表示オプション (showPostCount): 管理画面のデザインエディタに、カテゴリー名の隣に記事数を表示/非表示できるトグルチェックボックスを追加（例: 開発関連 (5)）。
• デザインエディタのリアルタイムプレビュー改善: デザインエディタ内で、最新記事・人気記事・カテゴリーメニューの各ウィジェットが実際のデータに近いプレースホルダーで正しく表示されるよう修正。
• 公開記事基準のスマート hreflang フィルタリング (SEO): 実際に公開記事が存在する言語に対してのみ hreflang タグを生成し、空の多言語ページが Google AdSense 等で価値の低いコンテンツ（Thin Content）と判定される問題を根本から防止。

🚀 Release v1.0.0.7

• エンジンバージョン管理の正式導入 (APP_VERSION): @sveltekitblog/shared パッケージにバージョン定数を追加し、管理画面サイドバーおよびブログフッターに現在稼働中のエンジンバージョンバッジを表示。
• 全ルート多言語メタデータの完全対応: ホーム、カテゴリー、タグ、検索、ゲストブックなどすべてのフロントエンドルートに hreflang および正規化URL (Canonical) を完全に適用。
• フッターのモバイル視認性改善: モバイル画面におけるバージョンバッジのコントラスト比とレイアウト余白を最適化。

🚀 Release v1.0.0.6

• モバイル Core Web Vitals およびパフォーマンス最適化: 動的OG画像生成、Google Fonts API キャッシュ、静的リソースのプリロードによりモバイル表示速度を改善。
• サイトマップの 500 エラー修正: sitemap.xml 生成ロジックから存在しない古いタグテーブルクエリを削除し、エラーのない安定したサイトマップ配信を保証。
• 動的 HTML lang 属性の最適化: アクセス言語コンテキスト（ko, en, ja）に応じて、ルートの HTML タグの lang 属性が正確に自動切り替えされるよう修正。
• 多言語 i18n キー構造の整理: 言語バッジ翻訳キーを common.lang.short_* グループへ統一。

🚀 Release v1.0.0.5

• Svelte 5 Runes 反応性警告の解消: 管理画面コンポーネント内の $state 反応性ステートに関するコンパイラ警告を修正。
• 管理画面デフォルトルートの整理: 管理画面ダッシュボードの導線およびフィードバックフローを改善。
• 正規化 URL (Canonical) の適正化: スラッシュの欠落および多言語 URL 間での正規化アドレスの不一致バグを修正。

🚀 Release v1.0.0.4

• NAVER ウェブマスターツール H1 重複エラーの解消: LayoutRenderer のレスポンシブ切り替えをモバイルファースト SSR 方式に改善し、クローラーが H1 タグを重複検出しないよう修正。
• フッターレイアウトの整列: ブログフッターの最大幅とボーダースタイルをヘッダーと統一し、シャドウ（影）のレン더リングを最適化。
• リポジトリのクリーンアップ: Git 追跡に誤って含まれていた一時ファイル（.bak）を整理。

Webサイトやブログを開発した後、次に直面する課題は「どうやってインターネット上に公開して訪問者に見てもらうか」ということです。

従来は、月額料金を支払ってVPS（仮想専用サーバー）を契約し、Nginxの設定やSSL証明書の更新などを手動で管理する必要がありました。しかし現在では、**Cloudflare Pages(CFP)**を活用することで、サーバー管理の負担なく、グローバルな超高速配信と寛大な無料枠（Free Tier）で簡単にサイトをデプロイできます。

本記事では、Cloudflare Pagesの概要をはじめ、手元のPCからデプロイする際の2つの認証方式（ブラウザログイン方式 vs APIトークン方式）の違い、そして記事や画像を保存するD1データベースとWorkers KVストレージの基本原理をわかりやすく解説します。

📂 1. Cloudflare Pages(CFP)とは？

一言で言えば、**「制作したWebサイトのファイルを世界中数百都市にあるCloudflareのエッジサーバーに配置し、訪問者に最も近い場所から超高速で配信するホスティングサービス」**です。

HTML、CSS、画像などの静的ファイルはもちろん、SvelteKitやNext.jsのようにサーバー側でリアルタイムに画面を描画するSSR（サーバーサイドレンダリング）やAPIルートも快適に動作します。

なぜ従来のVPSではなくCloudflare Pagesを選ぶのか？

• サーバー管理が一切不要: Linuxのセキュリティパッチ適用やNginxの設定、サーバー死活監視を行う必要がありません。Cloudflareが24時間安全にインフラを管理します。
• 圧倒的なグローバル配信速度: ユーザーのリクエストが中央の1台のサーバーに集中せず、物理的に最も近いエッジサーバーから即座に応答します。
• 優れたコストパフォーマンス: 個人ブログや一般的なポートフォリオのトラフィックであれば、無料プラン（Free Tier）の範囲内で十分に運用可能です。

🔑 2. 手元のPCからCloudflareへデプロイする2つの方法

SvelteKitアプリケーションをビルド（npm run build）すると、@sveltejs/adapter-cloudflareによって**.svelte-kit/cloudflare**ディレクトリに静的ファイルと実行用ワーカー（_worker.js）が生成されます。

このビルド成果物をCloudflare Pagesにデプロイする標準コマンドは**npx wrangler pages deploy .svelte-kit/cloudflare**であり、認証方式には大きく2種類が存在します。

[方法 1] 対話型ブラウザログインによるデプロイ（Wrangler標準方式）

単一アカウントで初めて始める際に最も直感的な方式です。コマンドを実行するとブラウザが開き、ログイン権限を承認します。

# SvelteKitビルド後にPagesへデプロイ（ブラウザログイン）
npm run build
npx wrangler pages deploy .svelte-kit/cloudflare --project-name=my-blog-web --branch=production

• 動作の仕組み: ターミナルでコマンドを実行すると、PCのWebブラウザが自動的に起動し、Cloudflareのログイン画面が表示されます。[Allow（承認）]をクリックするとローカル環境（~/.config/.wrangler）にセッションが保存され、デプロイが完了します。
• メリット: APIトークンを個別に発行する手間がなく、数クリックで手軽に連携できるため、個人ブログを1つのアカウントで始める際に最適です。
• 注意点:
  • 複数のCloudflareアカウントを切り替えてデプロイする場合、都度ログアウトと再ログインが必要になります。
  • 画面のないリモートサーバーやGitHub ActionsなどのCI/CD自動化環境では利用できません。

[方法 2] APIトークン環境変数による非対話型自動デプロイ（CI/CD・複数アカウント標準）

複数アカウントの運用やデプロイ自動化で使用される標準的な方式です。発行済みのAPIトークンを環境変数で渡すことで、ブラウザのポップアップなしで即座にデプロイします。

# 環境変数でトークンとアカウントIDを指定してデプロイ（PowerShell例）
$env:CLOUDFLARE_API_TOKEN="YOUR_API_TOKEN"
$env:CLOUDFLARE_ACCOUNT_ID="YOUR_ACCOUNT_ID_32_CHARS"
npx wrangler pages deploy .svelte-kit/cloudflare --project-name=my-blog-web --branch=production

• 動作の仕組み: Cloudflareダッシュボードで必要な権限（Pages、D1、KVなど）を持つAPIトークンを発行し、環境変数に登録しておきます。デプロイ実行時にこのトークンが自動的に渡され、ブラウザを開かずにバックグラウンドでデプロイが完了します。
• メリット:
  • ポップアップ画面が出ず、静かに高速にアップロードされます。
  • アカウントごとに異なるトークンを割り当てられるため、複数サイトを運用する際もセッション衝突を起こさず完全に独立デプロイが可能です。
• 準備: 初回のみCloudflareダッシュボードでAPIトークンを発行する手順が必要です。

💾 3. 記事や画像はどこに保存されるのか？（D1とKVの役割）

Webサイトのフロントエンド画面だけでなく、執筆した記事やアップロードした画像を安全に保管するストレージが必要です。Cloudflareは2種類のサーバーレスストレージを提供しています。

1. Cloudflare D1（リレーショナルSQLiteデータベース）:
   • 行と列で構造化されたエッジ分散型SQLデータベースです。
   • 記事のタイトル、本文（Markdown/HTML）、公開日時、カテゴリー、タグ、サイト基本設定など、検索や構造化が必要なデータを安全に保存します。
2. Workers KV（超高速Key-Valueストレージ）:
   • 読み込み処理に特化したグローバル分散Key-Valueストアです。
   • 記事に添付されたサムネイルや画像バイナリをエッジキャッシュに保持し、訪問者の要求に応じてミリ秒単位で素早く返します。

🧩 4. SvelteKitブログエンジンの実例構成

SvelteKitブログエンジン（SvelteKit Blog Engine）は、これらのCloudflareサーバーレスインフラを以下のように最適化して構成しています。

なぜブログ画面と管理画面を2つのPagesに分離したのか？

1つのアプリケーションに統合するのではなく、一般訪問者用apps/blogと管理者用apps/adminの2つの独立したCloudflare Pagesに分けてデプロイしています：

1. 攻撃対象領域（Attack Surface）の最小化: 管理者ログイン処理、Markdown/HTMLエディタ、設定変更APIなどの管理機能が一般公開バンドルに一切含まれません。別個のサブドメインで物理的に分離されるため、セキュリティが大幅に向上します。
2. 訪問者用バンドルの極限までの軽量化: 閲覧用サイトには重量のあるエディタライブラリや管理スクリプトが1バイトも含まれないため、モバイル端末でも極めて高速に初回ページが表示されます。

データの流れ

• 管理者が管理画面で記事を投稿・編集して画像をアップロードすると、データは共有の**D1（データベース）とWorkers KV（画像ストレージ）**に書き込まれます。
• 読者がブログWebサイトにアクセスすると、同じD1およびKVから最新のコンテンツを取得して高速に描画します。

🚀 5. まとめ

Cloudflare Pagesは、従来の複雑なサーバー保守や高額なホスティング費用を不要にし、誰もが快適で高性能なフルスタックWebアプリケーションを運用できる優れたプラットフォームです。

最初はブラウザログイン方式（wrangler login）で手軽にサイトを立ち上げ、サイトの規模拡大や複数アカウント運用に合わせてAPIトークン自動デプロイへと段階的に移行していくアプローチをおすすめします。

今回のリリースでは、管理者ポストエディターの利便性と機能を向上させるための複数の改善事項を反映しました。

🚀 主な変更点

1. 本文画像のリンク挿入および編集機能の追加

   • エディター内で画像を挿入・編集する際、画像にカスタムリンクURLおよび「新しいタブで開く」設定を連動できるようモーダルUIを拡張しました。
   • Tiptapエディター読み込み時に画像リンクが強制削除される問題を防止するため、HTML前/後処理（Pre/Post-processing）機能を連動しました。

2. 投稿作成/編集プレビューにおける画像キャプションの視覚化

   • 投稿プレビュータブで画像下の意味論的キャプション（<figcaption>）が正常にレンダリングされるよう、既存の本文処理ユーティリティを再利用して同期しました。

3. 多言語対応リアルタイム文字数カウンターの搭載

   • 記事作成・編集画面の下部に、純粋な文字数をリアルタイムで集計するカウンターUIを追加しました。
   • HTMLタグやMarkdown文法記号などを自動的に除去し、実際のテキスト文字数のみを精密にカウント。多言語設定にも完全対応しています。

v1.0.0.3 アップデート詳細

今回のリリースでは、ウィジェットシステムの構造的な欠陥を全面的に修正し、ウィジェット一覧のUIスタイルを統一しました。

🐛 バグ修正

1. ウィジェット新規作成直後の配置におけるレンダリングクラッシュの修正

   • 作成したばかりのウィジェットを即座にレイアウトへ配置する際、master- プレフィックスが漏れたまま保存され、レンダリングが崩壊していた致命的なクラッシュを修正しました。

2. デスクトップ/モバイルレイアウト配置時の config データ消失の修正

   • ウィジェットを配置する過程で設定値（config）が一切伝達されず、配置されたウィジェットが空の状態で保存されていたバグを修正しました。

3. ウィジェット編集モーダル表示時の設定値初期化バグの修正

   • 配置されたウィジェットの編集ボタンを押した際、config がすでにオブジェクトであるにもかかわらず JSON.parse を二重で実行して SyntaxError が発生し、モーダルの全設定（limit, shadow 等）が初期値にリセットされていたバ그を修正しました。

4. limit の不正入力に対するバリデーションの強化

   • ウィジェット作成・編集時に limit 値が不正な値（NaN、1未満）で保存される脆弱性を遮断し、該当する場合はデフォルト値 5 に正規化するよう修正しました。

5. 同一タイプウィジェット複数配置時のデータ取得範囲エラーの修正

   • 同じタイプのウィジェット（例：人気投稿）が複数配置された場合、1つ目のウィジェットの limit 基準でのみDBを検索し、残りのウィジェットが切れたデータを受け取っていた構造的バグを修正しました。同一タイプのウィジェットの中で最も大きい limit 基準で検索したのち、各ウィジェットが自らの設定に合わせて独立してデータを表示します。

🎨 スタイル

1. ウィジェット一覧の区切り線スタイルの統一
   • RecentPostsWidget と PopularPostsWidget の項目間区切り方式が異なり、視覚的な一貫性がなかった問題を修正しました。両ウィジェットとも border-bottom 区切り線と 0.5rem パディングで統一しました。

🎨 レイアウトラベルおよびデザインのマイナー調整

ブログのレイアウトやカラーなど全体のスタイル要素をマイナー調整し、画面構成が崩れることなく自然に馴染むよう整えました。

🛠️ 主なスタイル調整事項

1. テーマカラーおよびトーンの調整

   • オレンジ系のサブカラーをポイントとし、背景色全体およびカード領域の境界線・影の値を整え、視覚的な負担を軽減しました。

2. デスクトップ2段構成レイアウトの配置調整

   • 本文領域とサイドバー（カテゴリー、最新/人気投稿など）の横幅比率を再調整し、左右の余白とコンテンツの整列がずれないよう合わせました。

3. ヘッダー/フッターおよびモバイルメニューの配置整列

   • 上部ヘッダーの透明度調整とともに、モバイルメニューアイコンの整列状態および下部フッター領域のレイアウトがスマートに表示されるよう整理しました。

title: "【開発日記】2026-07-10"
slug: "devlog-2026-07-10"
category: "devlog"
categoryName: "開発日記"
tags: [ブログエンジン, リリース, v1.0.0.3, テーマ設定]
excerpt: "v1.0.0.2 & v1.0.0.3 リリースおよび新規テーマ適用"
authorId: "管理者"
thumbnailFit: "cover"

v1.0.0.2 アップデート詳細

今回のリリースでは、管理者ポストエディターの利便性と機能を向上させるための複数の改善事項を反映しました。

🚀 主な変更点

1. 本文画像のリンク挿入および編集機能の追加

   • エディター内で画像を挿入・編集する際、画像にカスタムリンクURLおよび「新しいタブで開く」設定を連動できるようモーダルUIを拡張しました。
   • Tiptapエディター読み込み時に画像リンクが強制削除される問題を防止するため、HTML前/後処理（Pre/Post-processing）機能を連動しました。

2. 投稿作成/編集プレビューにおける画像キャプションの視覚化

   • 投稿プレビュータブで画像下の意味論的キャプション（<figcaption>）が正常にレンダリングされるよう、既存の本文処理ユーティリティを再利用して同期しました。

3. 多言語対応リアルタイム文字数カウンターの搭載

   • 記事作成・編集画面の下部に、純粋な文字数をリアルタイムで集計するカウンターUIを追加しました。
   • HTMLタグやMarkdown文法記号などを自動的に除去し、実際のテキスト文字数のみを精密にカウント。多言語設定にも完全対応しています。

v1.0.0.3 アップデート詳細

今回のリリースでは、ウィジェットシステムの構造的な欠陥を全面的に修正し、ウィジェット一覧のUIスタイルを統一しました。

🐛 バグ修正

1. ウィジェット新規作成直後の配置におけるレンダリングクラッシュの修正

   • 作成したばかりのウィジェットを即座にレイアウトへ配置する際、master- プレフィックスが漏れたまま保存され、レンダリングが崩壊していた致命的なクラッシュを修正しました。

2. デスクトップ/モバイルレイアウト配置時の config データ消失の修正

   • ウィジェットを配置する過程で設定値（config）が一切伝達されず、配置されたウィジェットが空の状態で保存されていたバグを修正しました。

3. ウィジェット編集モーダル表示時の設定値初期化バグの修正

   • 配置されたウィジェットの編集ボタンを押した際、config がすでにオブジェクトであるにもかかわらず JSON.parse を二重で実行して SyntaxError が発生し、モーダルの全設定（limit, shadow 等）が初期値にリセットされていたバ그を修正しました。

4. limit の不正入力に対するバリデーションの強化

   • ウィジェット作成・編集時に limit 値が不正な値（NaN、1未満）で保存される脆弱性を遮断し、該当する場合はデフォルト値 5 に正規化するよう修正しました。

5. 同一タイプウィジェット複数配置時のデータ取得範囲エラーの修正

   • 同じタイプのウィジェット（例：人気投稿）が複数配置された場合、1つ目のウィジェットの limit 基準でのみDBを検索し、残りのウィジェットが切れたデータを受け取っていた構造的バグを修正しました。同一タイプのウィジェットの中で最も大きい limit 基準で検索したのち、各ウィジェットが自らの設定に合わせて独立してデータを表示します。

🎨 スタイル

1. ウィジェット一覧の区切り線スタイルの統一
   • RecentPostsWidget と PopularPostsWidget の項目間区切り方式が異なり、視覚的な一貫性がなかった問題を修正しました。両ウィジェットとも border-bottom 区切り線と 0.5rem パディングで統一しました。

🎨 レイアウトラベルおよびデザインのマイナー調整

ブログのレイアウトやカラーなど全体のスタイル要素をマイナー調整し、画面構成が崩れることなく自然に馴染むよう整えました。

🛠️ 主なスタイル調整事項

1. テーマカラーおよびトーンの調整

   • オレンジ系のサブカラーをポイントとし、背景色全体およびカード領域の境界線・影の値を整え、視覚的な負担を軽減しました。

2. デスクトップ2段構成レイアウトの配置調整

   • 本文領域とサイドバー（カテゴリー、最新/人気投稿など）の横幅比率を再調整し、左右の余白とコンテンツの整列がずれないよう合わせました。

3. ヘッダー/フッターおよびモバイルメニューの配置整列

   • 上部ヘッダーの透明度調整とともに、モバイルメニューアイコンの整列状態および下部フッター領域のレイアウトがスマートに表示されるよう整理しました。

1.
こんな状況になってしまったのは、正直YouTubeのせい度が大きい（？）。
遅まきながら個人開発者として何かやってみようと資料を探していると、とてつもない量の情報が溢れ出てくる。
問題は、情報の量は溢れているのに、実質的な質は散々な場合が多いということだ。

2.
ごく基本的な内容なら情報が多くても問題ないのだが、少し専門的だったり特殊な状況になると、「なんでこれが検索に引っかかって、自分は今Webでこれを見ているんだ？」と理解に苦しむほど全く無用な情報に遭遇したり、タイトルには欲しい情報が含まれているのに本文は単に文法を合わせただけの意味のない文字の羅列であるケースがかなりある。
これがYouTube動画だと、本当に腹が立つ。

3.
そんな中、たまに砂漠でオアシスに出会うように宝物のような情報をくれたのは、ほぼすべて開発者のブログ記事だった。
本当に嬉しかったし、ありがたかった。
そして、成人ADHDを疑うほどの私の集中力は、「あ、自分も開発者ブログを一つ立ち上げて誰かの役に立ち、コーヒー代くらい稼ぎたいな（？）」という決断を下すことになる。

4.
そうして既存のブログプラットフォームを再検討してみたが、どれも自分にとっては致命的な問題点が一つずつあった。
まず、デプロイや維持に費用が発生するものはすべて除外した。
まあコーヒー代くらい稼げれば嬉しいが、実際にそれが可能なレベルにするには本気で頑張らなければならないことを知っているし、自分は自分をよく知っている。
私はそんなに頑張れない。
だからこそ、最初から「設置・維持費用が絶対にかかってはならない」という結論を大前提として敷いた。
そこで最初に構想したのは、ProxmoxローカルサーバーにWordPressをインストールして使うことだった。
このように使うには最小限のセキュリティのためにL2スイッチとpfSenseのようなファイアウォール設置は必須だと考えた。
そうしてある程度構成を終えてからWordPressを改めて見直してみると、カスタムが難しすぎた。
これをカスタムするにはPHPを本格的に勉強しなければならないと判断した時点で、この方式は諦めることになった。

5.
そしてすぐに他の方法を探してみたが、結局どれも一つずつ引っかかった。
どんな方法であれ、導入すればそれについて新しく勉強しなければならないという点が非常に疲弊感として押し寄せてきた。
その疲弊感が「あ、もうシンプルに自分で作っちゃおう」という考えへと導いた。

6.
この時、すでに私はSvelteとSvelteKitで色々と遊び倒していたところだった。
ブログを作ること自体は非常に簡単な状況だった。
問題は、自分が作ったデザインを自分が信用できないということだった。
そこで、デザインを簡単に変更できる構造にしようとした結果、転がり転がってここまで来ることになった。

7.
実際にデザインエディタの高度化とデバッグに最も多くの時間を費やした。
最初に「シンプルなブログツール」を作ろうと決めて、一日でコードの90%ほどを完成させた。
そして実際にブログを作って運用してみた。
すると、「これも必要だな」「この機能も入れなきゃ」「これがあったら便利そう」「これはないとダメだろ」がほぼ無限に溢れ出てきた。
そうして昨年11月末に始まったプロジェクトらしきものが、今年3月に機能実装が一段落し、7月になってようやくGitHubオープンにこぎ着けた。

8.
気がつくと機能が増えすぎてコードも複雑になったため、途中でモジュール化やリファクタリングを行った。
システム自体を根底から覆すことも何度かあった。
最初は管理画面をProxmoxサーバーにインストールしてローカルからのみ接続可能にし、DBはSupabase、認証もSupabase Authを使っていた。
かなり深刻なコールドスタートと無料プランでは認証時にプロジェクト名が露出する状況を経験し、素直にCloudflareエコシステムを使うことにして、以前使ったことのあるBetter-authを搭載する計画へと変更した。
その後も内部的にロジックや構造を相当大きく変えることになった。
その上、Windows環境で作業を進めたせいで、何か一つ直すたびに実際のデプロイまで行わないと確認できず、本当に凄まじい遠回り（試行錯誤）をした。

9.
ほぼ終わりが見えてきた頃には、自分一人では到底修正もできないほどコードが肥大化していたため、自分でやった部分もあるが、大部分はGeminiにやらせて進めた。
さらにドキュメント化をしていなかったため、一つ一つ実際の機能と照らし合わせながらドキュメント化を進め、エラーを見つけては再び修正作業に入る…という状態だった。
このように3月から7月まで、ドキュメント化 ➔ エラー発見 ➔ 修正 の無限ループだった。
その間にも「これはないとダメだろ」と「この機能あったのにどこ行った？」が頻繁に飛び出して、本当に気が狂いそうだった。

10.
泣き面に蜂で、Geminiが本当に暴走する事態が非常に頻繁に発生した。
コード一行直せば済むものを関係のないモジュールをごっそり書き換えたりと、とにかくGeminiが暴れさえしなければ2ヶ月は早く終わっていただろうと確信している。
ともかくGitHubオープン直前まで極度のストレスに苛まれたが、最終的に「これはないと」という機能をすべて削ぎ落とし、できているものだけ整理して公開することに決めた。
それが v1.0.0.0 だった。

11.
その直後にすぐ v1.0.0.1 が出ることになる。
「できているもの」だけ整理して上げたはずだったのに、整理が不十分だった部分にすぐ気づいたのだ。
きっとこういう部分がまだあるだろうと確信していて非常に不安でもある。
公開した時点から直感していたので、あらかじめ v1.0.0.x のバージョンを切っておいたのかもしれない。

12.
…というわけで、こうしてSvelteKitブログエンジンが完成しました。
締めくくりが曖昧なので、PageSpeed Insightsのスコアでも載せて終わりにしたいと思います。
AdSenseは申請後審査待ちの状態ですが、すでにコードが挿入されており、CDNキャッシュも2分間隔に設定されているため、キャッシュがパージされて再生成される間にテストが行われるとパフォーマンスに影響を与えるのか、正確な理由は分かりませんが現在スコアの変動がかなり大きいです。
平均くらいが出た時のスコアですので、参考程度にご覧ください。
AdSenseが承認されたら、またPageSpeed Insightsのレポートを載せます。
それでは、良い一日を！ :)

本ガイドは、ターミナル（CMDまたはPowerShell）環境で自動化コマンド（npm run setup）を実行してCloudflareエッジインフラを構築し、管理者アプリとブログアプリを同時にデプロイ・同期する、最も簡単かつ安全な方法を案内します。

🛠️ 1. ワンクリックデプロイ自動化の紹介

SvelteKitブログエンジンは、複雑なサーバーリソースの生成や設定ファイルの編集プロセスを、ターミナル上の対話型インストールツールを通じて完全に自動化しました。

ブログのソースコードを解凍するか、git cloneでPCに保存した後、ターミナルを開いてプロジェクトのルートフォルダーに移動し、以下のコマンドを順番に実行するだけです。

# 必要なパッケージのインストール
npm install

• 依存関係ライブラリのインストール: ターミナルでnpm installを入力して、必要なパッケージをすべてインストールします。インストール完了後にセキュリティ警告（vulnerabilities）メッセージが表示された場合は、npm audit fixコマンドを実行して最新のセキュリティパッチを適用することをお勧めします。

パッケージのインストールが終わったらnpm run setupを実行します。ターミナル画面の案内に従って、以下のプロセスが自動的に処理されます。

• Cloudflareアカウントの簡単認証: クリック1回でデプロイアカウントの連携が完了します。
• DBおよびストレージリソースの生成: ブログ専用のD1データベース2個と画像保存用のKVストレージを自動的に新規生成します。
• 設定ファイルのリアルタイム更新: 生成されたデータベースの固有IDを検出し、モノレポの設定ファイル（wrangler.json）に自動的に注入します。
• データベースの初期データ注入: テーブルを生成し、選択したデフォルト言語に合わせてサンプル記事と基本環境設定情報を自動的に登録します。
• 環境変数とアクセス許可IPのアップロード: 管理者アクセス用に、デプロイ実行者の現在のパブリックIPアドレス（ALLOWED_IP）と管理者パスワードをクラウドへ自動送信します。
• 統合ビルドおよびWebサービスのデプロイ: ブログと管理者のSvelteKitプロジェクトを統合ビル드し、Cloudflare Pagesへ即時にアップロード・デプロイします。

📋 2. デプロイ前の確認事項

安全にインストールを開始する前に、以下の準備がすべて整っているかご確認ください。

1. Node.jsのインストール: パソコンでNode.js（バージョン22以上）が動作している必要があります。
2. Cloudflareアカウント: ブログサイトとデータベースをホスティングするCloudflareアカウント（無料枠で十分対応可能です）が必要です。
3. 環境変数ファイル（.dev.vars）の生成（必須）:
   • デプロイを開始する前に、apps/admin/フォルダとapps/blog/フォルダの配下に、それぞれ.dev.varsファイルを手動で作成する必要があります。
   • apps/admin/.dev.varsファイルには、ADMIN_PASSWORD=管理者ログインパスワードを記述します。
   • apps/blog/.dev.varsファイルには、BETTER_AUTH_SECRET=任意の文字列を記述します。

   • [!WARNING]
     これらの環境変数が設定されていない場合、npm run setupの実行直後に、正常な動作のためにインストールツールが中断されます。

⚙️ 3. npm run setup ステップ別解説

ターミナルを開き、ブログプロジェクトのルートディレクトリでnpm run setupを入力してEnterキーを押します。

Step 0. 環境変数の事前検査（Pre-Validation）

• 実行直後に、管理者およびブログフォルダ内の.dev.varsファイルと、必須の環境変数（ADMIN_PASSWORD、BETTER_AUTH_SECRET）が入力されているか検査します。
• 未入力の項目がある場合は、ガイドログを表示して終了しますので、事前に必ず記載しておいてください。

Step 1. デプロイプロジェクト名（ドメインURL）の設定

• 読者がブログにアクセスする際に使用するアドレス（例：[入力したプロジェクト名].pages.dev）を決定する段階です。
• デプロイターゲットであるブログと管理者の2つの名前を入力します。復元モード（--restore）で実行する場合、既存のバックアップ情報ファイル（wrangler.backup.json）から既存の名前を自動的に読み込んで設定します。

Step 2. Cloudflareアカウントのログイン認証

• Cloudflareの認証を確認します。すでにログイン履歴がある場合は、自動的にセッションを検出してこの手順をスキップします。
• ログインしていない場合は、ブラウザウィンドウが開き認証要求画面が表示されます。**[Allow / 許可]**をクリックしてアカウント連携を承認してください。
• セキュリティ情報：本自動化ツールは、インフラ生成およびデプロイに必要な最小限のアカウントAPI権限のみを要求するため、安心してお進みください。

Step 3. リソース生成および設定の連携

• 実際のサービス動作に必要なデータベースとメディアストレージをクラウドに生成する段階です。ターミナルの案内に従って、適切な番号を入力してください。
  1. 1（新規インストール / Fresh Install）: 以前に作成されたデータベースとストレージを完全に削除して新しく作成し直します。 既存のデータはすべて消去されるためご注意ください。
  2. 2（既存データの維持 / Keep Existing Data）[推奨]: すでに生成されたリソースがある場合、データを安全に保持したまま接続情報のみを紐付けます。
• 連携完了後、新しく発行されたDBおよびKVの固有IDがモノレポの各設定ファイル（wrangler.json）に自動的に反映されます。

Step 4. Webプロジェクトの事前生成

• デプロイの安定性を高めるため、Cloudflare Edge上に空のWebプロジェクトをあらかじめ登録・確保します。
• すでに同じ名前のアドレスが占有されている場合は、既存のアドレスを再利用して次のステップへ自動的に移行します。

Step 5. 環境変数のリモート同期

• ローカルで作成した.dev.vars内のマスターパスワードなどの秘密の値をCloudflareへ安全にアップロードして同期します。
• アクセス許可IPの自動登録: 特にこの段階で、デプロイを実行している管理者PCのパブリックIPアドレスをリアルタイムで検出し、ALLOWED_IP変数として自動的に注入します。これにより、デプロイ直後の初回ログイン時にIP制限でアクセスできなくなる事態を防ぎます。

Step 6. データベーステーブルの構築＆デフォルトテーマの設定

• ブログ機能の動作に必要なDBテーブルを構築し、初期設定値を移植します。
• 画面の案内に従って使用するデフォルトの言語（韓国語、英語、日本語）を選択すると、翻訳システムが構築され、サンプルカテゴリ、ヘッダーメニューの骨組み、およびデフォルトのウェルカム記事が自動的に設定されます。

Step 7. Webサービスのビルド＆最終デプロイ

• モノレポ全体のアプリの統合ビルドを実行し、Cloudflareサーバーへのデプロイコマンドを自動実行してインストールプロセスを完了します。デプロイが完了すると、ブログと管理者のPagesアクセス用URLが表示されます。

[!TIP]

💡 環境変数の自動設定と即時アクセスサポート

本プロジェクトのインストールプロセスは、リソースの生成からWebプロジェクトの確保、環境変数の送信までを一貫して処理します。
デプロイ完了と同時に、ログインパスワードやIPアクセス許可設定がリモートサーバーに設定されるため、追加の手動操作なしで即座に動作します。

🔄 4. ブログのアップデートとデータ復元デプロイ（npm run restore）

ブログの運用中に新しいパッチバージョンやバグが修正された最新リリースのコードが配布された際、これまでに作成した記事データやアドレスを失うことなく、新しいコードへ安全に画面を差し替える方法です。

💡 新バージョン移行の4ステップ手順

管理者のデータバックアップと**npm run restore**コマンドを使用すれば、データ消失のリスクなく安全にアップグレードを完了できます。

1. [ステップ1] 既存データおよびデプロイ設定のバックアップ:
   • 稼働中の管理者アプリの**コンテンツバックアップメニュー、およびデザインエディタ**メニューの下部バックアップセクションから、記事データとテーマデザイン設定をそれぞれパソコンへダウンロードします。
   • また、**コンテンツバックアップ**メニューの「設定バックアップダウンロード」ボタンをクリックして、[wrangler.backup.json]ファイルをPCに保存します。（これは、既存の運用データベースの固有ID連携を維持するための最も重要なファイルです。）
2. [ステップ2] 新コードの分離テスト:
   • 新しく入手した新バージョンのコードフォルダ配下でnpm run setupを実行し、テスト用の仮DBとテスト用のPages仮デプロイ名を入力して別個にデプロイします。
   • 仮デプロイされた新しい管理者にログインし、ステップ1で保存したバックアップデータファイルをインポートして、データが正常に読み込まれるか事前に確認します。
3. [ステップ3] 既存の運用サーバーへのバインディング復元（npm run restore）:
   • 検証が終了したら、新バージョンプロジェクトのルートディレクトリに、ステップ1で保存したwrangler.backup.jsonファイルをコピーして貼り付けます。
   • ターミナルで**npm run restoreコマンドを実行します。スクリプトがバックアップファイルに記述された既存の運用DBおよびKVの固有ID情報**を読み込み、新しいコードの設定ファイルへ上書きの形で自動接続します。
4. [ステップ4] スキーマ同期と上書きデプロイ:
   • 復元スクリプトは既存の運用DBのテーブル構造スキーマのみを安全に最新仕様へ更新するため、すでに蓄積されている実際の記事やデータは破損または削除されず完璧に保持されます。
   • 続いて、npm run deploy:blogとnpm run deploy:adminをそれぞれ実行します。使用していたドメインそのままで、最新にアップグレードされたブログシステムが安全に上書きデプロイされます。

📦 5. バックアップファイルの種類と機能

管理者のバックアップメニューで安全にインポートおよびエクスポートできる各ファイルの役割は、以下の表をご参照ください。

本ドキュメントは、ブログシステムを制御するために管理者が管理者（アドミン）ページへ安全にアクセスし、ログインセッションを維持して、画面上の様々なテキスト（多言語辞書）を簡単に管理・編集する方法を案内します。

🔒 1. 管理者ログイン前のIPセキュリティ制限ポリシー

本ブログエンジンは、外部からの不正アクセスや投稿権限の乗っ取りを完璧に防ぐため、厳格な接続IPフィルタリングセキュリティポリシーを採用しています。デプロイ時に検出された管理者のパブリックIPアドレスのみが、サーバーの許可リスト（ALLOWED_IP）に登録され、アクセスが許可されます。

[!IMPORTANT]

🛡️ 安全地帯中心の運用原則（公共の場所での使用禁止）

本ブログの管理者画面での操作は、必ず自宅や信頼できるオフィスなど、物理的・ネットワーク的なセキュリティが確保された場所でのみ行ってください。
セキュリティ漏洩を防止するため、不特定多数が利用しハッキングのリスクに直接さらされるPC房（ネットカフェ）、図書館、公共Wi-Fi環境などの公共の場所では、管理者画面への接続自体を一切推奨せず、避けていただきますよう強くお願いいたします。

接続許可された安全な場所であっても、ルーターの再起動やインターネット回線の都合によりパブリックIPアドレスが変更され、403 Forbiddenブロック画面が表示された場合は、以下の手順に従って許可リストを手動で更新する必要があります。

⚙️ 接続許可IPアドレスの更新手順（再デプロイが必要）

1. 変更されたインターネット環境下でターミナルを開き、ブログサービスの管理者アプリを再度**再デプロイ（Redeploy）**するコマンドを実行します。
2. 作業プロセスの案内: データベース内部を直接編集してIPを強制的に書き込む極端な動作方法よりは安全ですが、再デプロイコマンドが実行されるたびにビルドプロセスとファイルアップロードの待機時間が数分間発生するため、実質的にはかなり面倒で手間の伴う作業です。
3. デプロイスクリプトの実行中に、現在接続されているコンピュータの新しいパブリックIPアドレスを検出し、リモートサーバーの許可IPリストを最新のものに更新します。
4. デプロイ処理が完了した後に管理者URLへ再アクセスすると、正常にログイン画面が再び有効になります。
5. 管理者ページのみを再デプロイしてください。

🔑 2. 管理者ログインおよびセッション管理

ログインのブロックが正常に解除されたら、初期構築時に設定した管理者マスターパスワード（ADMIN_PASSWORD）を入力して接続します。

• 安全なセッションの維持: ブラウザの専用セキュアクッキー設定を利用して、30日間管理者のログインセッションが安全に維持されます。
• 公共のコンピュータおよび危険区域へのアクセス禁止:
  セキュリティが保証されていないネットカフェや公共の共有デバイス環境では、管理者ログイン自体を試みないことが最も確実な防衛策です。万が一、やむを得ない事情で公共の環境からログインした場合は、作業終了直後に必ず管理者画面下部の**[ログアウト]**ボタンをクリックし、さらにターミナルでnpx wrangler logoutを実行して、そのコンピュータに記録されたCloudflare管理者アカウントの連携情報まで確実に解除（ログアウト）してください。

[!WARNING]

🔒 管理者ページのアクセスURL（ドメイン）露出の最小化を推奨

管理者画面はIP許可リストにより二重で安全に保護されていますが、攻撃対象領域（Attack Surface）そのものを最小化することが最も堅牢なセキュリティ対策です。

そのため、admin.myblog.comのような分かりやすいカスタムドメインをわざわざ紐付けるのではなく、Cloudflare Pagesからデフォルトで提供されるランダムなサブドメインアドレス（例：[プロジェクト名].pages.dev）をそのまま使用し、管理者用のアクセス経路を秘密にしておくことを強く推奨します。

🌐 3. 多言語辞書（i18n）設定ガイド

記事の本文以外の、サイト画面に固定されている共通テキスト（メニューラベル、コメント送信ボタン、ログインプロンプトなど）は、ソースコードを1行も修正することなく、管理者の辞書編集機能を通じて英語、韓国語、日本語などに即時書き換えることができます。

新しい対応言語は、言語を追加 機能を使用して登録することができます。ただし、新しく追加した言語が画面上に正しく表示されるようにするには、既存の辞書に登録されているすべての翻訳キー（Key）に対して、該当言語の翻訳テキストを漏れなく入力しておく必要があります。

1. 管理者画面の左側メニューから**言語設定**メニューに移動します。
2. 現在サイト全域で使用されている各翻訳キーと保存されたテキストの一覧が、下部の**UI多言語辞書エディタ**セクションに表示されます。
3. 編集したいキーの入力フィールドに希望のテキスト（韓国語、英語、日本語）を入力し、その行の右端にある**保存**アイコンをクリックします。
4. 保存と同時にライブサイトへ即時に反映され、訪問者がブログの言語を切り替えた際、変更後のテキストでリアルタイムかつスムーズに翻訳表示されます。

本ドキュメントは、多言語記事の同時パブリッシュ、デバイス別レイアウト設定、リアルタイムデザインテーマ設定など、管理者（管理画面）が提供する主要機能の基本構成と概要を紹介します。

📝 1. 多言語記事の作成およびデュアルエディタ

記事作成メニューに入ると、複数の言語タブが1つの画面に並んだ多言語作成環境が提供されます。

① 多言語記事の一括作成と保存

• 作成フロー: 上部の言語タブ（KO、EN、JAなど）を切り替えながら、各言語に応じたタイトル、概要、スラッグ（URLパス）、本文を入力します。
• 一括保存: 下部の [すべてのタブを同時に保存する] ボタンをクリックすると、入力したすべての言語の記事がデータベースに一括で保存されます。 「公開」 設定がされていない言語は自動的に 「下書き」 として保存され、入力されていない言語タブはデータが生成されずにスキップされます。

② デュアルエディタのサポート（ビジュアル vs Markdown）

• ビジュアルHTMLエディタ（Visual）: 一般的なWebエディタのように、書式を設定したりメディアを埋め込んだりして直感的に作成する方式です。画像ファイルはツールバーのアップロードボタンから簡単に挿入できます。

• Markdownエディタ（Markdown）: Markdown構文を好むユーザー向けに提供されています。タイトル、概要、カテゴリ、タグなどの情報は、ヘッダー領域にYAML Front Matter（---）形式で自動的に管理されます。保存時には、Markdownソースと変換後のHTML本文が一緒に保存されます。

③ 代表画像（サムネイル）の自動指定

• サムネイル画像が手動で指定されていない場合、システムが本文を分析して代表画像を自動的に設定します。
  • 第1優先: 本文内で最初に使用されている画像。
  • 第2優先: 本文に画像がなく、YouTubeのリンクやiframe埋め込みが含まれている場合、その動画の公式高解像度サムネイルURL。

🧱 2. デバイス別（デスクトップ/モバイル）の独立ウィジェット配置

レイアウトエディタでは、ドラッグ＆ドロップでサイドバーや本文領域のウィジェットカードの並び順を調整できます。また、訪問者のデバイスタイプ（デスクトップまたはモバイル）に応じて、独立したウィジェット露出設定を構成できます。

⚙️ デバイス別のウィジェット表示条件

1. デザインエディタ メニュー内の ブログ構造 タブから、全体のレイアウト構成と横幅の比率を選択します。
2. 各ウィジェットの追加・編集時に、露出デバイス条件（Device）を指定できます。
   • Desktop (デスクトップ専用): PC画面にのみウィジェットを表示し、モバイル接続時には不要なリソースの読み込みを遮断します。
   • Mobile (モバイル専用): PC画面では非表示にし、スマートフォンやタブレットなどのモバイル解像度でのみ表示されるように制限します。
3. 効果: モバイルユーザーに対して不要または重いウィジェットのレンダリングや読み込みをスキップすることで、ページの読み込み速度とスクロールパフォーマンスを最適化します。

🎨 3. リアルタイムデザインエディタとテーマ設定

デザインエディタで変更したテーマカラーやスタイル情報は、サーバーの再ビルドやデプロイを行わずに、保存後すぐに訪問者のブラウザのCSS変数へ反映されます。

• 4種類の背景タイプ: 単色（Solid）、グラデーション（Gradient）、背景画像（Image）、HTML5 Canvasアニメーション（Canvas）から選択できます。
• グラスモフィズム効果: 背景画像を使用する際、テキストの視認性を確保するために不透明度（Opacity）とぼかし（Blur）を調整するガラス越しのような効果の設定をサポートしています。
• インタラクティブCanvas: サンドボックスで隔離された安全なキャンバス内で、雪、波、星座などの動きのあるモーションアートワークを背景として駆動できます。

[!TIP]
背景設定オプションの種類とサンプルスクリプトは、デザインエディタ設定の紹介 文書でご確認いただけます。

💾 4. メディアストレージのサポート

本文で使用するメディアが保存されるクラウドストレージを、必要に応じて柔軟に切り替えて運用できます。

1. メディアライブラリ メニュー下部の ストレージ設定 領域へ移動します。
2. 連携するストレージタイプを選択し、情報を入力します。
   • Cloudflare KV: エッジノードのKVストレージにアセットを保管し、迅速に配信します。
   • Cloudflare R2: 大容量オブジェクトストレージを使用し、コスト効率よく画像を管理します。
   • Supabase Storage: Supabaseのストレージバケットパスにメディアをアップロードして安全に保管します.
   • ImageKit.io: グローバル画像CDNプラットフォームと連携し、アップロードした画像の解像度最適化や圧縮処理を活用します。
3. ストレージのリアルタイム切り替え: 変更を保存すると、アップロードエンジンが指定したストレージへ即座に切り替わります。

[!NOTE]
標準メディアストレージ (Cloudflare KV) のエクスプローラー機能の制限
Cloudflare KVは、Workersの使用量とコストの最適化のため、画像エクスプローラー内での一覧表示（読み取りAPIの呼び出し）をサポートしていません。一方、Cloudflare R2、Supabase Storage、ImageKit.ioなどの外部ストレージを設定して接続した場合は、アップロードされた画像の一覧表示やプレビュー機能をすべて利用できます。

本ドキュメントは、再ビルドや再デプロイを必要とせずにテーマ設定を即座に反映するシステムと、4つの背景設定（単一色、グラデーション、背景画像、カスタムJavaScriptキャンバス）の基本構成について紹介します。

🌌 1. リアルタイムデザインエディタの概要

デザインエディタで設定値を変更して保存する際、ブログサーバーやCDNサービスを再ビルド・再デプロイする必要は一切ありません。保存するとデータベースが即座に更新され、訪問者のブラウザ画面にCSS変数と背景レンダリングモジュールが1秒で反映されます。
ブログに最終適用する前に、管理者ページ内のプレビュー画面でデザインの変化をあらかじめ確認することができます。

[!WARNING]

⚠️ プレビューと実際のブログデザインの差異に関する注意点

デザインエディタのプレビュー機能は、実際の訪問者画面と100%同一のレンダリング環境を保証するものではありません。 ブラウザによるCSS変数の解釈やJavaScript Canvasの描画条件などにより、管理者ページのプレビューと実際のブログ表示に微細な差異が生じる場合があります。

それゆえ、デザイン設定を変更した後は、必ず実際のブログのメイン画面にアクセスし、再読み込み（F5）を行って最終的な表示状態を確認することを強く推奨します。

🧱 レイアウト＆テーマ設定項目

① レイアウト構成

• ブログ基本構造: メインページの基本レイアウト構造（例：2カラム、3カラムなど）を選択できます。
• カラム幅の比率: メインコンテンツエリアとサイドバーカラムの横幅比率（例：1:2:1、2:1:2など）を調整します。
• 最大横幅: ブログ画面全体の最大横幅解像度（例：1200px、1400pxなど）を制限します。
• レイアウト詳細設定: 左右の余白（Side Margin）、カードコンテナの角の丸み（Border Radius）、立体感を与えるシャドウ（Box Shadow）効果を細かく制御します。

② テーマ基本配色

• メインテーマ色（Primary）、サブ色（Secondary）、本文テキスト色（Text）、アクセント強調色（Accent）、カード背景色（Card Bg）、および枠線色（Border）をカスタマイズできます。

③ タイポグラフィ（フォント）設定

• Google Fontsのフォント一覧から任意のフォントファミリー名を直接入力して適用し、本文のフォント種類や基本文字サイズ（Base Font Size）を設定できます。

④ ウィジェットの配置・順序管理

• 使用可能なウィジェットをドラッグ＆ドロップで各カラムに自由に配置し、表示順序を調整できます。

🧱 2. デバイス別の独立ウィジェット配置

レイアウト設計時には、ドラッグ＆ドロップでサイドバーや本文領域のウィジェット位置と順序を調整できます。また、訪問者の画面サイズ（デバイスタイプ）に応じてレイアウトを動的に切り替えるフィルタリング機能を提供します。

• Desktop (デスクトップ専用): 画面幅の広いPC環境でのみ、指定されたウィジェット（例：タグクラウド、カテゴリツリーなど）を表示します。モバイル接続時には、読み込み速度を維持するため、HTML送信段階で該当要素をあらかじめ除外します。
• Mobile (モバイル専用): デスクトップ環境では非表示にし、スマートフォンなどのモバイル解像度でのみモバイル向けに表示されるよう制限します。

🌈 3. 4つの背景設定の種類

ブログ全体の雰囲気を決定する背景画面として、以下の4つのタイプがサポートされています。

① Solid（単一色背景）

• 任意のHEXコード（例： #3b82f6）またはHSLカラーコードを指定して、最もシンプルで記事本文に集中しやすい画面を構成します。

② Gradient（グラデーション背景）

• グラデーションビルダーツールを使用して、複数のカラーがスムーズに混ざり合う線形グラデーションを作成します。
• 角度（Direction）スライダーの調整やカラーストップ（Stops）の追加・移動により、開始色、中間色、終了色を自由に配合できます。

③ Image（背景画像＆グラスモフィズム効果）

• 背景に使用する画像のURLを入力するか、アップロード（Upload）ボタンを使用してメディアファイルをライブラリに追加します。
• アップロード画像の最適化: 画像を登録すると、システムが自動的にWebP形式へ変換し、読み込みパフォーマンスの低下を防ぎます。
• グラスモフィズム効果: 背景画像がテキストの視認性を妨げないよう、以下の設定を組み合わせて半透明なガラス窓風のスタイルを構成できます。

④ Custom JavaScript（カスタムJavaScript＆Canvas背景）

• クライアントのブラウザ背景にインタラクティブなCanvasアニメーションを描画するため、カスタムJavaScriptの入力をサポートします。
• 背景キャンバス要素（canvas id="bg-canvas"）に対して直接描画を制御できます。連動するセキュリティ制限や省電力ポリシーの詳細は、以下の [4. カスタムJavaScript連携仕様] で説明します。

⚡ 4. カスタムJavaScript連携仕様

セキュリティリスクを防止し、モバイル端末のバッテリー消費を抑えるため、以下のサンドボックス環境および省電力システムが適用されています。

🔒 サンドボックス＆CSPによるセキュリティ制限

悪意あるスクリプトの混入による脆弱性を防ぐため、以下のセキュリティ対策が常時稼働しています。

1. 隔離されたサンドボックス構造: キャンバスコードは、スクリプト実行のみが許可された隔離された iframe 内で動作します。親ページのDOMノードやログイン情報などへのアクセスは技術的に遮断されます。
2. コンテンツセキュリティポリシー (CSP) 制限: 外部サーバーへのネットワーク通信や外部スクリプトの呼び出しが全面的に遮断されます。これにより、外部サーバーへデータを流出させることが不可能です。
3. JS APIの制限: セキュリティ上のリスクとなる fetch, XMLHttpRequest, WebSocket, eval, new Function, document.cookie, localStorage などのAPIが検出された場合、検証スクリプト（jsValidator.ts）によって自動的にコメント処理（/* f_e_t_c_h (blocked) */）されます。

🔋 バッテリー消費の最適化（省電力技術）

• 画面外での自動一時停止: ユーザーがスクロールして背景アニメーションが完全に視野から外れると、ブラウザが不要にCPU/GPUを消費しないよう、レンダリングループを スリープ状態（一時停止） に切り替えます。再び画面に表示されると、即座に再開されます。
• モバイル用フレーム制限: スマートフォンやタブレットでアクセスする場合、発熱を抑えるためデフォルトで背景スクリプトの実行を停止します。「モバイル端末でもアニメーションを実行」 オプションを明示的に有効にした場合は実行が可能となり、その際もパフォーマンスに負荷がかからないようパーティクル数を自動的に削減する制御パラメータが適用されます。

📝 5. サンプルスクリプト3種

背景設定メニューから [Custom JavaScript] を選択し、以下のコードのいずれかをコピーして適用できます。

[!NOTE]
スクリプトを作成する際は、描画対象のキャンバス要素を取得するために必ず document.getElementById('bg-canvas') のID名を使用してください。

❄️ サンプルA. 冬の雪（Snowfall）

画面上部から雪の結晶がゆっくりと舞い落ちる背景アニメーションです。

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  // モバイル省電力の判定
  const divisor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) || 1;
  const maxSnowflakes = Math.floor(100 / divisor);
  const snowflakes = [];
  
  class Snowflake {
    constructor() {
      this.reset();
      this.y = Math.random() * height; // 初期ランダム高度
    }
    
    reset() {
      this.x = Math.random() * width;
      this.y = -10;
      this.radius = Math.random() * 3 + 1;
      this.speed = Math.random() * 1 + 0.5;
      this.opacity = Math.random() * 0.6 + 0.2;
    }
    
    update() {
      this.y += this.speed;
      // 緩やかな揺らぎ
      this.x += Math.sin(this.y / 30) * 0.5;
      
      if (this.y > height || this.x < 0 || this.x > width) {
        this.reset();
      }
    }
    
    draw() {
      ctx.beginPath();
      ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
      ctx.fillStyle = `rgba(25, 25, 255, ${this.opacity})`;
      ctx.fill();
    }
  }
  
  // パーティクルの生成
  for (let i = 0; i < maxSnowflakes; i++) {
    snowflakes.push(new Snowflake());
  }
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    
    for (let i = 0; i < snowflakes.length; i++) {
      snowflakes[i].update();
      snowflakes[i].draw();
    }
    requestAnimationFrame(animate);
  }
  
  // リサイズハンドラ
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
  });
  
  animate();
})();

🕸️ サンプルB. 星座ネットワーク（Constellation Network）

浮遊するノードパーティクル同士が近づいた際に、薄い半透明の線で結ばれ網状のネットワークを形成する背景アニメーションです。

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  const divisor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) || 1;
  const particleCount = Math.floor(80 / divisor);
  const particles = [];
  const connectionDistance = 100;
  
  class Particle {
    constructor() {
      this.x = Math.random() * width;
      this.y = Math.random() * height;
      this.vx = (Math.random() - 0.5) * 0.8;
      this.vy = (Math.random() - 0.5) * 0.8;
      this.radius = Math.random() * 2 + 1.5;
    }
    
    update() {
      this.x += this.vx;
      this.y += this.vy;
      
      // 境界での反射
      if (this.x < 0 || this.x > width) this.vx *= -1;
      if (this.y < 0 || this.y > height) this.vy *= -1;
    }
    
    draw() {
      ctx.beginPath();
      ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
      ctx.fillStyle = 'rgba(99, 102, 241, 0.4)'; // パステルインディゴ
      ctx.fill();
    }
  }
  
  for (let i = 0; i < particleCount; i++) {
    particles.push(new Particle());
  }
  
  function drawLines() {
    for (let i = 0; i < particles.length; i++) {
      for (let j = i + 1; j < particles.length; j++) {
        const dx = particles[i].x - particles[j].x;
        const dy = particles[i].y - particles[j].y;
        const dist = Math.sqrt(dx * dx + dy * dy);
        
        if (dist < connectionDistance) {
          const alpha = (connectionDistance - dist) / connectionDistance * 0.18;
          ctx.beginPath();
          ctx.moveTo(particles[i].x, particles[i].y);
          ctx.lineTo(particles[j].x, particles[j].y);
          ctx.strokeStyle = `rgba(99, 102, 241, ${alpha})`;
          ctx.lineWidth = 1;
          ctx.stroke();
        }
      }
    }
  }
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    for (let i = 0; i < particles.length; i++) {
      particles[i].update();
      particles[i].draw();
    }
    drawLines();
    requestAnimationFrame(animate);
  }
  
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
  });
  
  animate();
})();

🌊 サンプルC. 穏やかな波（Fluid Sine Waves）

画面下部でパステル調の半透明な複数の波が緩やかに揺れる背景アニメーションです。

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  let wave1 = {
    y: height * 0.85,
    length: 0.005,
    amplitude: 25,
    frequency: 0.012
  };
  
  let wave2 = {
    y: height * 0.88,
    length: 0.008,
    amplitude: 15,
    frequency: 0.022
  };
  
  let increment = 0;
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    
    // 背景の波の描画 (半透明ティール)
    ctx.beginPath();
    ctx.moveTo(0, height);
    for (let i = 0; i < width; i++) {
      ctx.lineTo(i, wave1.y + Math.sin(i * wave1.length + increment) * wave1.amplitude);
    }
    ctx.lineTo(width, height);
    ctx.fillStyle = 'rgba(45, 212, 191, 0.1)';
    ctx.fill();
    
    // 手前の波の描画 (半透明スカイブルー)
    ctx.beginPath();
    ctx.moveTo(0, height);
    for (let i = 0; i < width; i++) {
      ctx.lineTo(i, wave2.y + Math.sin(i * wave2.length - increment * 1.5) * wave2.amplitude);
    }
    ctx.lineTo(width, height);
    ctx.fillStyle = 'rgba(56, 189, 248, 0.15)';
    ctx.fill();
    
    // デバイスの設定に応じた速度の調整
    const speedFactor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) ? 0.3 : 1;
    increment += wave1.frequency * speedFactor;
    
    requestAnimationFrame(animate);
  }
  
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
    wave1.y = height * 0.85;
    wave2.y = height * 0.88;
  });
  
  animate();
})();

📱 6. モバイル個別背景設定

利用環境に合わせて背景設定を変えることで、システムのパフォーマンスを最適化できます。

1. デスクトップ背景: PC環境では Custom JavaScript を選択し、任意のCanvasアニメーションを実行できます。
2. モバイル個別背景チェック: 「モバイルデバイスでデスクトップと異なる背景設定を使用する」 トグルを有効にします。
3. モバイル背景の軽量化: 独立したモバイル設定パネルから背景を Solid または Gradient に設定し、モバイル端末のプロセッサ負荷を最小限に抑えます。
4. 効果: スマートフォン接続時には軽量な背景を選択することでバッテリーを保護し、PC接続時には豊かなビジュアルモーション効果を最大限に表現するというイネーブル化が可能です。

❓ 管理者のよくある質問 (FAQ) およびトラブルシューティング

本ドキュメントは、ブログのインストール、デプロイ、および運営段階で発生する可能性のある主なトラブルシューティング解決策と、安全な最新バージョンへのアップグレードガイドを提供します。

🗄️ Q1. 最新バージョンへ安全にアップグレード（Upgrade）するか、データを復元する方法を教えてください。

データベースの整合性を維持し、予期しないビルドクラッシュを防ぐため、以下の安全なアップグレード手順を遵守することを強く推奨します。

1. 安全な最新バージョンへのアップグレード検証手順（推奨）

既存のデータベースとのスキーマ不一致やテンプレート変更に伴う衝突を予防するため、本番サーバーに直接適用するのではなく、まず隔離されたテスト環境で安全性を確認してください。（Gitを使用せずファイルを直接ダウンロードして使用するユーザーも同様です）

1. 設定ファイルのバックアップ:
   • 現在の開発フォルダ内にある wrangler.backup.json と .dev.vars ファイルを安全な一時フォルダにコピーして保管します。
   • ※ .dev.vars ファイルは重要な認証情報（パスワード、OAuthキーなど）を含みますが、セキュリティ保護のためGit管理対象外（.gitignore）に指定されています。そのため、コードの更新時や再取得時に紛失しやすいため、必ずバックアップを取ってください。
2. 稼働中のデータバックアップ:
   • 現在稼働しているブログ管理画面の コンテンツバックアップ メニューから、記事全体および設定バックアップファイルをダウンロードします。
3. 隔離されたフォルダに新バージョンをクローン/ダウンロード:
   • 既存のフォルダを上書きせず、完全に新しいディレクトリに最新リリースのソースコードをダウンロードまたはクローンします。
4. 一時テストサーバーのデプロイ:
   • 新しいフォルダに移動し、依存関係のインストール（npm install）を行い、一時的なテスト用データベースを構築してテストデプロイを実行します。
5. バックアップ復元テスト:
   • 新しくデプロイされたテスト用管理画面にアクセスし、ステップ2で取得したバックアップファイルをロードして、データが漏れなく正常に表示され、エラーが発生しないかを徹底的に検証します。
6. 本番サーバーへの正式アップデート適用:
   • テストサーバーですべての機能が正常に動作することを確認した後でのみ、元の開発フォルダに戻り、コードを更新（git pull またはソースコードの上書き）して、各アプリの個別デプロイコマンド（npm run deploy:blog、npm run deploy:admin）を実行し、正式なアップグレードを完了させます。

2. データ紛失時の最終手段

• npm run restore コマンドの使用:
  • インフラ設定やデータベースが深刻に破損し、根本的な復旧が必要な場合にのみ、バックアップしておいた wrangler.backup.json ファイルを基にインフラ全体を再構築する**「最後のデータ復旧手段」**として実行してください。

📂 Q2. R2、Supabase、ImageKitへの画像ストレージ変更時に入力すべき必須キーは何ですか？

各外部画像ストレージ使用時に入力漏れのないよう確認すべき必須環境変数および設定のチェックリストです。

📊 Q3. ダッシュボードの統計グラフがデモデータのみで表示されます。

• 原因: Google Analytics 4 (GA4) APIの環境変数が入力されていない、または無効な場合、ダッシュボードのクラッシュを防ぐためにデモ用のダミーデータが代替表示されます。
• 設定手順: Cloudflare Pages設定に以下の環境変数を入力し、再デプロイを行ってください。
  • GA4_PROPERTY_ID: Google Analytics プロパティ ID
  • GA4_CLIENT_EMAIL: Google Cloud サービスアカウントメールアドレス
  • GA4_PRIVATE_KEY: Google サービスアカウント秘密鍵
• 注意点: .dev.vars ファイルに GA4_PRIVATE_KEY を記述する際、改行コード（\n）の形式が崩れないよう、必ず鍵文字列全体を二重引用符（"）で囲って登録してください。

⚡ Q4. 初回setupデプロイ後、管理画面にアクセスできなかったり、一部のデータ同期が不足しているようです。

• 原因: ワンクリックセットアップ時に環境変数の設定が正常に完了していたとしても、一時的なネットワーク接続エラーやシステム上の不具合により、暗号化キーや秘密環境変数（Secrets）の同期が一部抜けてしまったり、データが破損した状態でデプロイが進行することがあります。
• 解決策: 各アプリの .dev.vars 設定値の状態を再度確認した上で、各フォルダに移動し、手動で個別のデプロイコマンド npm run deploy:blog と npm run deploy:admin をそれぞれ 1回実行 してください。ローカルの .dev.vars ファイルに入力された秘密環境変数群が正常に上書きされることで、問題が解決します。

🔒 Q5. 管理画面へのアクセス時に「Forbidden (IP Not Allowed)」または403エラーが表示されます。

本ブログのセキュリティ仕様上、デプロイスクリプトの実行時にデプロイを行っているPCのグローバルIPアドレスを自動的に検知し、アクセス許可IP（ALLOWED_IP）としてPages Secretに自動挿入します。

⚠️ 管理者セキュリティ推奨事項

• アカウントの乗っ取りや不正アクセスを防ぐため、外部の公共エリア（カフェ、図書館など）や、信頼性の保証されない 共有PC からの管理画面へのアクセス・投稿作業は、セキュリティ保護のため強く制限することを推奨します。

💡 状況別の対処法

• 状況A. 自宅やオフィスのIPアドレスが変わった場合（ルーターの再起動など）:
  • 既存の作業を行っていた自宅やオフィスのメイン開発PCのターミナルから npm run deploy:admin を1回実行してください。変更後のグローバルIPを自動的に検知して再デプロイが行われ、即座にアクセスが再開されます。
• 状況B. やむを得ず外部の場所から投稿作業を行うため、一時的に開発環境を移動させる場合:
  • 以前取得したバックアップ設定ファイル（wrangler.backup.json など）を持参し、新しいPC環境でワンクリックセットアップを実行して、新規にビルド・デプロイすることでアクセス権限を取得する方法が最も簡単です。
  • ※ 注意: 外部での作業を終え、再び本来の自宅やオフィスに戻ってブログを管理する際には、必ず元のメイン開発PCから npm run deploy:admin を再実行し、アクセス許可IPを本来の固定IPに復元デプロイしてください。

🔐 Q6. Better Auth（ソーシャルログイン・会員登録）に関するエラーや、ログインの無限ループが発生します。

• 原因: 認証セキュリティに使用される環境変数が欠落しているか無効な場合、セッション検証に失敗してログイン画面がループし続けます。
• 解決策:
  1. apps/blog/.dev.vars を開き、BETTER_AUTH_SECRET に 最小32文字以上の安全なランダム暗号化文字列 が入力されているか確認します。
  2. 正確に値を設定した後、npm run deploy:blog を実行して秘密キーを同期上書きすれば、認証機能が正常に復旧します。

本ドキュメントは、ブログ（apps/blog）トップ画面のレイアウト構成と、基本的な会員登録およびログイン方式の概要を紹介します。

🎨 1. ブログの画面構成とレイアウト

ブログの画面は、訪問者が情報を迅速に見つけられるよう、直感的なレイアウト（ヘッダー、本文、サイドバー、フッター）で設計されています。

1. ナビゲーションヘッダー (Header):
   • サイトロゴ: クリックするといつでもトップ画面に戻ります。
   • ショートカットメニュー: カテゴリへのショートカットや外部リンクなど、主要なリンクが表示されます。
   • 多言語切り替え: 地球儀アイコンをクリックすると、メニュー言語や記事の翻訳版をリアルタイムで切り替えて表示できます。
2. サイドバー (Sidebar):
   • PC画面では、カテゴリ一覧、運営者プロフィールカード、人気タグなどが表示され、自由な探索をサポートします。
   • モバイル端末からのアクセス時には、本文の視認性向上のため自動的に非表示になります。
3. メインコンテンツ領域 (Main Content):
   • 最新の記事一覧とカテゴリフィルターが、カードデザイン形式で配置されています。

🔑 2. 会員登録とログイン

コメントの入力やゲストブックへのメッセージ作成に必要な、アカウント作成およびログイン機能をサポートしています。

⚙️ ログインおよび登録サポート方式

• 標準メールログイン/登録 (Default):
  • インストール直後にデフォルトで有効化されているログイン方式です。メールアドレス、表示名（ニックネーム）、パスワードを登録して新規登録でき、登録後は即座に自動ログインが適用されます。

本ドキュメントは、訪問者がブログの多言語翻訳記事を閲覧し、コメントやゲストブックを通じて他のユーザーと対話するための主要機能を紹介します。

🌐 1. 記事本文のリアルタイム言語切り替え (i18n)

このブログは、メニューやボタンなどの基本的なUIだけでなく、作成された記事本文データ自体も選択した言語バージョンに切り替えて閲覧できる、リアルタイム多言語翻訳ビューアを提供しています。

⚙️ 動作方式と特徴

• 言語別URLルーティング: 上部の地球儀アイコンまたは記事タイトル横の言語選択ボタンをクリックすると、URLアドレスに言語コードのプレフィックス（例：/en, /ja）が付与され、該当言語の専用ページへ即座にルーティングされます。デフォルトで提供される言語（韓国語、英語、日本語）だけでなく、管理者が多言語翻訳辞書（ディクショナリ）を追加定義することで、新たな言語バージョンを制限なく追加発行できます。

• 手動作成データの読み込み（自動翻訳ではありません）: システムが自動的にリアルタイムで機械翻訳を行うわけではありません。作成者が各言語タブの翻訳記事本文データを直接執筆して個別に保存しておくと（外部AIや翻訳機で加工したものをデータベースにそれぞれ登録）、訪問者が選択した言語に対応する記事データをデータベースから正確に呼び出し、画面にレンダリングする方式です。
• 本文およびメタデータの同時読み込み: 単純なテキストの置き換えにとどまらず、データベースに各言語向けに登録されているタイトル、概要、タグ、本文HTMLが、完全に選択した言語の個別データに切り替わって出力されます。
• 未翻訳記事の代替（フォールバック）表示: 作成者が特定の言語の翻訳記事を登録していない場合、訪問者がコンテンツを閲覧できなくなるのを防ぐため、「翻訳準備中」の案内メッセージとともに、デフォルトの作成言語（例：韓国語本文）で記事内容を代替表示し、スムーズな読書をサポートします。

💬 2. コメントおよび返信（スレッド）機能

各記事の下部には、ゲスト訪問者や会員が意見を交換できるコメント領域が配置されています。

• 意見の共有: ログインユーザーは、コメント入力欄に内容を記入して登録することで、即座に意見を共有できます。
• 階層型の返信（スレッド表示）: 特定のコメントに対して返信を行うことができ、スレッドの対話の流れをツリー構造でわかりやすく整理します。
• セキュリティと完全性の維持: 自分が作成したコメントは削除が可能です。ただし、すでに返信がついているコメントを削除する場合、会話の階層構造が崩れるのを防ぐため、「削除されたコメントです」というメッセージにマスク処理され、構造自体は保持されます。

📖 3. ゲストブックと非公開メッセージの作成

ゲストブック（Guestbook）を通じて、ブログの開設者とプライベートにコミュニケーションをとる機能をサポートしています。

⚙️ 非公開ゲストブック機能

• 非公開メッセージの作成: メッセージ入力時に [🔒 非公開で作成] チェックボックスを有効にすることで、非公開メッセージの送信が可能です。
• 表示権限の制限: 非公開で保存されたメッセージは、第三者（他の訪問者や未ログインの他ユーザー）のリストからは完全に除外されます。
• 安全なメッセージ送信: メッセージを作成した本人（ログイン状態）とサイト管理者のみに本文が表示され、安全に対話を行うことができます。

❓ 読者ポリシーとよくある質問 (FAQ)

本ドキュメントは、ブログサービス利用時に発生する可能性のある退会に伴う個人情報および作成データの処理方法、利用制限ポリシーなどの基本原則を紹介します。

🚪 Q1. 退会した場合、これまで作成したコメントやゲストブックはどうなりますか？

ブログシステムは、読者の個人情報保護とサイト内における対話の流れの整合性を同時に維持するため、**「作成者の匿名化処理ポリシー」**を適用しています。

💡 退会時の個人情報処理原則

1. 個人識別情報の削除:
   • 退会処理が行われると、ログインメールアドレス、ソーシャルプロファイル画像、ニックネームなど、会員を識別できる固有データはデータベースから即座に削除されます。ただし、不正加入および不正利用の防止、セキュリティ監査(Audit)を目的として、退会時のメールアドレスやソーシャルIDなどの最小限の情報が、隔離された内部脱退ログテーブル(deleted_users)にアーカイブ(バックアップ)されます。このログ情報は内部管理用であり、公開画面上からは作成者の特定や追跡が不可能なように完全に匿名化（作成者不明）処理されます。
2. 作成データの保持:
   • 作成されたコメントやゲストブックの投稿は、これまでの会話の流れや文脈を保持するため、テキスト内容は画面上にそのまま維持されます。
3. ニックネームの匿名化処理:
   • 作成者ニックネームとアカウント間の連携情報が解除され、作成者表示名は自動的に 「作成者不明」 に一括で切り替わります。これにより、以前の作成者が実際に誰であったかをシステム的に逆追跡することが防がれます。

• 参考：管理者が会員情報を直接完全に削除した場合には、作成されたコメントやメッセージも一緒に削除されることがあります。

🚪 Q2. 退会後、すぐに再登録（再加入）は可能ですか？

• 自主退会の場合:
  • 本人の意思で退会手続きを完了した場合、特別な憂慮期間なく、同一のメールアドレスやソーシャルアカウントを使用して即座に再登録およびサービス利用が可能です。
• 利用制限（Ban）状態の場合:
  • 運営ポリシー違反によってアカウントが利用制限（Ban）されている間は、該当のメールアドレス情報がすでにデータベース上に存在するため、同一のメールアドレスで新たに再登録することは原則として不可能です。
• 強制退会（Kick）処理された場合:
  • 管理者によってアカウントが強制削除（Hard Delete）された場合、認証テーブルから既存の情報が完全に削除されるため、同一のメールアドレスでの即時再登録が技術的に可能になります。
  • 内部脱退ログ（deleted_users）に強制退会時のメールアドレスおよびソーシャルID情報は保管されますが、現時点では登録時にこのログを照合して自動的に再入会を制限するシステム上のフィルタリング（ブロック）ロジックは実装されておりません。
  • したがって、同一人物による悪意ある活動の再発を物理的かつ完全に防ぐためには、アカウントを強制削除（Kick）する代わりに、「永久利用制限（Ban - ブロック済み）」 状態を維持することを推奨します。（Ban状態ではメールアドレスがデータベースに残るため、一意の制約によって同一メールアドレスでの再登録が遮断されます。）

🚫 Q3. アカウント利用制限（Ban）または強制退会（Kick）処理されました。

スパム広告や誹謗中傷などの運営ポリシー違反により、サービスの一部利用制限（Ban）措置が適用された、または強制退会（Kick）された場合の確認事項です。

💡 利用制限適用時の確認事項

1. 利用制限 (Ban):
   • 状態: ログイン状態は維持されますが、コメント作成、返信、ゲストブック登録など、サイト内における直接的な活動権限が一時的または永久に制限されます。
   • 理由の確認: 制限が適用されると、コメント作成エリアに 「ブロックされたユーザーはコメントを書き込めません。」 という案内メッセージが表示され、具体的な制限事由や制限満了日（解除予定日時）を確認できます。
2. 強制退会 (Kick/Delete):
   • 状態: ログインアカウント自体がデータベースから完全に削除（Hard Delete）された状態です。
   • 動作: 強制退会処理が完了すると、アクティブなログインセッションが即座に強制終了されます。その後ログインを試みた場合は、登録履歴のない新規会員（存在しないアカウント）として扱われます。管理者が設定した削除動作（deleteBehavior）によって、書き込まれたコメントがすべて一括削除されるか、作成者名が「作成者不明」として匿名化されて残るかが異なります。

📖 ブログと管理者機能の統合紹介

本ドキュメントは、ブログサービスおよび管理者機能（管理画面）の主要構成を一覧できるよう、個別の機能紹介ドキュメントを整理して案内します。

参考：各機能の具体的な連携手順や詳細なマニュアルは、後日個別の投稿を通じて順次案内される予定です。

📂 主要機能の紹介一覧

• 管理者（管理画面）機能紹介
  • CMDワンクリックインストールとCloudflareデプロイガイド: ターミナルコマンド一行でCloudflareエッジインフラを構築し、ブログをデプロイする方法を案内します。
  • 管理画面の初回アクセスと環境設定の開始: マスターパスワードログイン、接続許可IP（ホワイトリスト）管理および多言語UI辞書環境設定の概要を紹介します。
  • 管理者主要機能とデュアルエディタ紹介: ビジュアルHTMLエディタとMarkdownエディタを切り替えながら執筆し、デバイス別レイアウトウィジェットを配置する方法を紹介します。
  • リアルタイムデザインエディタと背景演出紹介: テーマカラー、単色/グラデーション/背景画像/キャンバススクリプトの4種類の背景設定を、再ビルドなしでリアルタイムに反映する機能を紹介します。
  • 管理者よくある質問 (FAQ) およびトラブルシューティング: バージョンアップグレード、画像ストレージキーの点検、デプロイ後の不具合解消およびIPセキュリティブロック解除方法などを確認します。
• ブログ機能紹介
  • ブログ初期画面構成とログイン: ブログの画面レイアウト構成とメール・ソーシャルログイン方式を紹介します。
  • ブログ主要機能と多言語サービス紹介: 多言語本文のリアルタイム切り替えおよび未翻訳時の代替処理ロジック、階層型コメントと非公開ゲストブックを通じたコミュニケーション構造を扱います。
  • 読者ポリシーとよくある質問 (FAQ): 退会時の作成データ処理原則、再登録の規定および利用制限（Ban）/強制退会（Kick）措置に関して確認します。

🚀 ブログ管理の基本プロセス

管理者の権限を設定し、執筆を開始する基本的な流れの概要です。

1. IP許可リストの適用とログイン

• 初めて管理画面にアクセスする際、セキュリティのため訪問者のグローバルIPアドレスが許可リスト（ALLOWED_IP）に登録されている必要があります。
• ログイン画面で設定された管理者マスターパスワードを入力して接続を確立します。

2. 多言語記事の一括保存

• 記事作成メニューに用意された多言語タブを切り替えながら本文をそれぞれ入力し、下部の保存ボタンをクリックしてデータベースへ多言語の記事データを一括で保存します。

3. リアルタイムテーマの適用

• デザインエディタでテーマカラー、フォントの種類、背景効果（Canvas、画像など）を保存すると、再ビルドなしに訪問者のブラウザ画面へリアルタイムで即座に反映されます。

💬 おわりに

本ドキュメントで紹介した内容は、ブログと管理画面が提供する機能の簡単な概要です。実際には、ここでは取り上げきれなかった様々な詳細機能や便利なオプションがさらに多く用意されており、実際にお使いいただきながらひとつずつ発見していくのも、また一つの楽しみになるかと思います。

今後、各機能の詳細な使い方や活用のコツを盛り込んだ詳細ガイドも順次投稿していく予定ですので、必要な際にまたお越しいただければ幸いです。ご利用中にご不明な点やお問い合わせがございましたら、ゲストブックやコメントを通じていつでもお気軽にお寄せください。

🚀 SvelteKit Monorepo + Cloudflare ワンクリックデプロイ＆自動セットアップ詳細説明書

本プロジェクトは SvelteKit モノレポ環境を基盤としており、サーバーレスデータベースである Cloudflare D1 と KV Namespace、そして Cloudflare Pages デプロイインフラを有機的に使用しています。

モノレポのマルチアプリケーション構造で発生しがちな、データベース接続情報の紛失、環境変数の不一致、手動 CLI によるバインディング設定の複雑さを最小限に抑えるため、ワンクリック自動セットアップスクリプトが標準で内蔵されています。このマニュアルでは、スクリプト実行前に準備すべきローカル環境設定から、実行中に表示されるターミナル選択プロンプトの意味とモード別の活用方法まで詳しく紹介します。

📂 1. スクリプト実行前の事前準備事項

セットアップスクリプトは、実行中の予期せぬエラーによる強制終了を防ぐため、Step 0 段階で必須のローカル環境変数（.dev.vars）が正しく用意されているか事前に検証します。スクリプトを実行する前に、必ず以下の準備を完了させてください。

🔑 1-1. .dev.vars ファイルの作成と必須値の設定

プロジェクトのルートディレクトリを基準に、ブログアプリと管理（Admin）アプリそれぞれのパスにある .dev.vars.example ファイルをコピーして .dev.vars ファイルを作成し、適切な値を記入します。

1. ブログアプリ用環境変数

   • 場所: apps/blog/.dev.vars
   • 必須設定項目:

     BETTER_AUTH_SECRET="任意の長いランダムな文字列"
     

     (認証セッションとトークンを暗号化するために使用される、固有かつ複雑な秘密文字列を記入します。空のままにしたり、ダブルクォーテーションのみの場合は検証に失敗します。)

2. 管理（Admin）アプリ用環境変数

   • 場所: apps/admin/.dev.vars

   • 必須設定項目:

     ADMIN_PASSWORD="管理者ログインパスワード"
     

     (管理者ダッシュボードへのログイン時に使用するパスワードを記入します。)

   • Google Analytics 4 (GA4) ＆ Google AdSense のダミーデータ表示について:
     もし管理者ダッシュボードのメイン画面で、GA4 アクセス統計や AdSense 実績レポートの**ダミーデータ（シミュレーション用の表示例）を確認して動作テストをしたい場合は、ローカルの .dev.vars ファイルおよび Cloudflare Pages のリモート設定から、Google 連携関連の環境変数（GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID など）の項目を空にするか、完全に削除（またはコメントアウト）**してください。連携に必要なキーが1つでも不足している場合、システムは自動的にダミーデータ表示モードを有効にします。

[!WARNING]
これらのファイルが存在しない、あるいは必須値が空の場合は、ターミナルに以下のような警告メッセージが表示され、セットアップが強制中断されます。

❌ apps/admin/.dev.vars ファイルが存在しません。
   (apps/admin/.dev.vars.example ファイルをコピーして作成し、ADMIN_PASSWORDを設定してください。)

🛠️ 2. コマンドの種類と実行方法

💬 3. 実行段階別ターミナルプロンプトガイド (Prompt Guide)

スクリプト実行中にターミナル画面に表示される実際の日本語・英語プロンプトと、各選択肢がインフラに与える影響について解説します。

🌐 3-1. 共通初期プロンプト (npm run setup & setup:select 共通)

Q1. デフォルトブログ言語の選択 (初期シードデータの言語設定)

D1 データベースに最初に注入される初期のガイド記事および基本設定の言語を決定します。

  [EN] Select default blog language:
  [KO] 기본 블로그 언어를 선택하세요:
  1) Korean / 한국어 (ko) [Default]
  2) English / 영어 (en)
  3) Japanese / 日本語 (ja)
  [EN] Choose option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  > 

• ガイド: デフォルト値である 1 を選択すると韓国語の初期データが生成されます。2 を入力すると英語、3 を入力すると日本語に翻訳された初期ガイドデータがデータベースに登録されます。

Q2. 進行モードの選択

残りのセットアッププロセスを完全に自動で実行するか、カスタマイズしながら手動で入力するかを決定します。

  [EN] Choose setup mode for the remaining steps:
  [KO] 나머지 설정의 진행 방식을 선택하세요:
  1) Full Auto Setup & Deploy / 풀 자동 설정 및 배포 [Default]
  2) Custom Interactive Setup / 사용자 지정 직접 선택 설정
  [EN] Choose option (1/2) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 1]
  > 

• 1) Full Auto Setup & Deploy (デフォルト値): ブログおよび管理画面の Pages プロジェクト名を基本規格（svelteblog, svelteadmin）で自動生成し、Cloudflare ログイン状態を検証後、すべてのマイグレーションとデプロイを自動で完了させます。
• 2) Custom Interactive Setup: 詳細カスタム設定モードに移行し、後述する追加質問（Q3〜Q8）が順次表示されます。 (npm run setup:select コマンドを実行した場合は、最初からこのモードで開始されます。)

🎨 3-2. カスタム対話型プロンプト (npm run setup:select 専用)

[!TIP]
カスタム対話型セットアップで表示されるすべての質問プロンプトは、値を入力せずにそのままエンターキー（Enter）を押すだけで、角括弧 [Default: ...] に表示されている安全なデフォルト値が自動で適用されます。そのため、複雑な入力を行わずエンターを連打して進行しても全く問題ありません。

Q3. デプロイプロジェクト名のカスタム

Cloudflare Pages 上に新規作成するデプロイプロジェクトの名前を指定します。 (デフォルトのアクセス URL は https://[プロジェクト名].pages.dev になります。)

  [EN] Enter Blog project name [Default: svelteblog]
  [KO] 블로그 배포명을 입력하세요
  > 

  [EN] Enter Admin project name [Default: svelteadmin]
  [KO] 어드민 배포명을 입력하세요
  > 

• ガイド: 空欄のままエンターキーを押すとデフォルト名が使用されます。Cloudflare アカウント内で他のプロジェクト名と重複しないように固有の名前をつけたい場合は、手動で入力してください。 (入力すると、package.json 内のビルド・デプロイスクリプトも自動でそのプロジェクト名に書き換わります。)

Q4. Cloudflare アカウントのログイン実行可否

Cloudflare API 制御のための認証処理を判定します。

  [EN] Run wrangler login?
  [KO] Wrangler 로그인을 진행할까요?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  > 

• ガイド: ログインが完了していない場合はブラウザが立ち上がり、認証ページに案内されます。既にログイン済みのセッションが検知された場合は自動的にスキップされますが、別のアカウントで再ログインしたい場合は Y を入力してください。

Q5. データ初期化モードの設定 (Fresh vs Keep)

既存の Cloudflare 上のリソース（D1 データベースや KV）のデータを初期化するかどうかを選択します。

  [EN] Select Initialization Mode:
    1: Fresh Install (DELETE existing Cloudflare D1/KV databases and start clean)
    2: Keep Existing Data (Use existing Cloudflare databases to preserve your posts/data)
  [KO] 초기화 모드 선택:
    1: 완전 초기화 (기존 클라우드플레어의 D1/KV 데이터베이스를 모두 삭제하고 새로 생성합니다. 데이터 유실 주의!)
    2: 기존 데이터 유지 (기존에 구축된 클라우드플레어 리소스를 그대로 유지하고 연동합니다.)

  [EN] Choose an option (1/2) [Default: 2]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 2]
  > 

• Fresh Install (1): 既存の D1 データベースと KV Namespace を完全に削除して新規作成します。テスト環境の構築など、まっさらな状態から再開したい場合以外は選択しないでください。
• Keep Existing Data (2, 推奨/デフォルト値): 既に登録されている記事やユーザー情報などのデータを維持したまま、バインディング情報（接続先ID）のみを同期します。

Q6. Cloudflare リソース名の指定

Cloudflare のダッシュボード上で実際に表示される D1 インスタンス名および KV インスタンス名を指定します。

  [EN] Enter Blog DB name [Default: blog-db-xxxxxx]
  [KO] 블로그 DB 이름을 입력하세요
  > 

  [EN] Enter User DB name [Default: user-db-xxxxxx]
  [KO] 유저 DB 이름을 입력하세요
  > 

  [EN] Enter Images KV name [Default: blog-images-kv-xxxxxx]
  [KO] 이미지 KV 이름을 입력하세요
  > 

• ガイド: 明示的に管理したい特定のデータベース名がある場合は手動入力し、そうでない場合はそのままエンターを押してランダムサフィックス（xxxxxx）が付与されたユニークな名前で自動生成されるようにします。

Q7. Cloudflare CDN キャッシュパージ設定の登録

ブログの記事を追加・修正した際に、エッジサーバー上のキャッシュを即時クリアし、読者に最新の記事内容が即座に反映されるようにするためのパージ用認証情報を登録します。

  [EN] Configure Cloudflare CDN cache purge credentials?
  [KO] CDN 캐시 퍼지 설정을 등록하시겠습니까?
  [EN] (y/N) [Default: N]
  [KO] (y/N) [기본값: N]
  > 

• ガイド: y を押すと、Cloudflare ダッシュボードの Overview 画面右下で確認できる Zone ID と、APIトークン設定から取得した API Token の入力プロンプトが始まります。入力された資格情報は、ローカルの .dev.vars および Cloudflare Pages 上に安全に同期されます。

Q8. 即時デプロイの実行確認

セットアップ完了後、その場ですぐにアプリケーションのビルドおよび Cloudflare Pages へのデプロイを実行するかどうかを選択します。

  [EN] Deploy directly?
  [KO] 지금 바로 배포하시겠습니까?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  > 

• ガイド: リソースの接続設定（wrangler.json への書き込み）完了後、すぐに実際の Web サーバーへ反映したい場合は Y を押します。ビルド完了後、最終的に生成されたサービスURLが出力されます。接続設定のみを行いたい場合は n を入力してください。

🔒 3-3. デプロイ同期時の条件付き追加プロンプト (IP & 翻訳辞書)

ビルドおよびデプロイ処理（sync-secrets.js）へ進むと、管理者ページのセキュリティや多言語辞書の保護を判定するためのプロンプトが追加で発生します。

Q9. 管理画面アクセス IP の不一致検知時の処理

管理者ダッシュボードは、不正アクセスを防ぐためにホワイトリスト形式の IP 制限（ALLOWED_IP）を採用しています。スク립トは現在のデプロイマシンのパブリック IP を自動で特定し、保存されている許可リストに含まれていない場合に以下の質問を表示します。

  1) Keep existing allowed IPs / 기존 목록 유지 (현재 기기 미등록) [Default]
  2) Add current machine IP to list / 현재 기기 IP를 목록에 추가 (복수 허용)
  3) Replace with current machine IP / 현재 기기 IP로만 갱신 (기존 목록 제거)

  [EN] Select option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  > 

• 1) Keep existing allowed IPs (デフォルト値): 現在のホワイトリストを変更せず維持します。 (現在のネットワーク環境が登録済みの許可 IP と異なる場合、デプロイ完了後に管理画面へアクセスできなくなる可能性があります。)
• 2) Add current machine IP to list: 既存の許可 IP リストを残したまま、現在デプロイを実行しているネットワークの IP アドレスをカンマ（,）区切りで追加します。自宅や職場など、複数の場所からアクセスを想定している場合はこちらを選択してください。
• 3) Replace with current machine IP: 登録されていた他の許可 IP をすべて削除し、現在のマシンのパブリック IP アドレスのみをホワイトリストに登録します。

Q10. データベース内多言語翻訳辞書の更新処理

Admin アプリのデプロイ時、モノレポの共通翻訳定義ファイル（packages/shared/src/i18n/index.ts）に開発者が定義した初期翻訳構造（fallbackDictionary）を、リモート D1 データベースの blog_settings テーブルに上書き保存するかどうかを確認します。

[EN] Force sync remote D1 ui_dictionary with local index.ts? (Web changes will be lost)
[KO] D1 DB의 ui_dictionary를 로컬 index.ts 기준으로 강제 덮어쓰시겠습니까? (웹 수정본 유실 주의)
  [EN] Select option (y/N) [Default: N]
  [KO] 옵션을 선택하세요 (y/N) [기본값: N]
  > 

• ガイド: もし既に管理画面の『設定ダッシュボード』等からユーザー自ら翻訳文を直接書き直している場合は、上書きによりその編集内容が消去されてしまうため、N（デフォルト）を推奨します。ローカルコードで編集した新規翻訳辞書を強制的にサーバーへ同期したい場合のみ y を入力してください。 (なお、初期セットアップ時には整合性を保つため自動で強制同期が行われます。)

🔄 4. バックアップと復元メカニズム (npm run restore)

セットアップが正常に完了すると、プロジェクトルートに wrangler.backup.json ファイルが自動生成されます。

{
    "d1": {
        "BLOG_DB": { "name": "blog-db-xxxxxx", "id": "d1-uuid-value" },
        "USER_DB": { "name": "user-db-xxxxxx", "id": "d1-uuid-value" }
    },
    "kv": {
        "IMAGES_KV": "kv-namespace-id"
    },
    "blogProjectName": "svelteblog",
    "adminProjectName": "svelteadmin"
}

このバックアップファイルがあることで、将来的にPCを変更したり環境を再構築する際に npm run restore コマンドを使用して安全に復旧することができます。

• 復元モードでは、プロジェクト名やデータベース等のリソースIDのバインディングが完全に自動で固定・適用されます。
• 稼働中のデータを上書きしないよう、初期シード（Seeding）データの投入プロセスが安全にスキップされるため、既存の投稿や会員情報を失うことなくデプロイ環境のリンク関係のみを復元できます。

❓ 5. トラブルシューティング

🚨 1. Wrangler Whoami セッションおよび権限エラー

• 現象: D1 や KV などのリソース生成コマンド実行時に、認証エラーやセッションなしのエラーが表示される。
• 解決: npm run setup:select を動かし、Q4. Wrangler ログインの段階で Y を入力してブラウザによる再認証を行ってください。スクリプトはアカウントセキュリティのために最小限の権限（account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write）のみを要求します。

🚨 2. Windows 環境でのスクリプト実行制限エラー

• 現象: Windows の PowerShell などでスクリプトの実行ポリシーにより動作がブロックされる。
• 解決: スクリプトは Windows を検知すると自動的に npx の代わりに npx.cmd を呼び出して回避するように設計されていますが、基本的には通常の PowerShell よりも Git Bash または **コマンドプロンプト（CMD）**を使用して実行することをお勧めします。

🔑 CLI環境におけるCloudflare WranglerログインおよびAPIトークン設定詳細説明書

本プロジェクトは、1回のコマンド実行だけでCloudflareのデータベース、ストレージ、ビルドパイプラインを自動構築するセットアップスクリプトを提供しています。

このスクリプトは内部的にCloudflareのコマンドラインツールである wrangler CLIを使用します。通常のローカル開発PC環境では、Webブラウザを介した対話型ログイン（npx wrangler login）が即座に実行されますが、**ブラウザを開くことができない完全なCLI環境（例：リモートSSH Linuxサーバー、ヘッドレス仮想マシン、CI/CDデプロイパイプライン）**では、ログインセッションを対話式に確立できない制約が発生します。

本マニュアルでは、この環境の制約を克服するため、Cloudflare APIトークンを活用してWranglerの非対話型認証セッションを安全に構築する方法を詳しく解説します。

📂 1. ドメイン設定の前後に伴う必須最小限の権限区分

APIトークンを発行する前に、現在のインフラデプロイ段階を把握することが重要です。不要なセキュリティリスクを抑えるため、カスタムドメインの接続状況に応じて必要な権限を分離して適用します。

🔌 1-1. 初期デプロイ段階 (カスタムドメイン連携前)

プロジェクトを初めてデプロイし、Cloudflare Pagesが提供するデフォルトドメインである *.pages.dev アドレスのみを使用する場合、ブラウザ経由の一般的なログイン状態と同様に、Zone（ドメイン）レベルの権限は一切不要です。 オ직 アカウント（Account）レベルの主要なリソース権限のみで、セットアップスクリプトの実行とD1のマイグレーションが問題なく動作します。

• 必須最小限の権限リスト:
  • D1 — 編集 (Edit) (D1 DBの作成、スキーマイグレーションの実行、クエリ動作用)
  • Workers KV ストレージ (Workers KV Storage) — 編集 (Edit) (ブログメディアアップロード用のKVネームスペース制御用)
  • Cloudflare Pages — 編集 (Edit) (モノレポのブログおよび管理画面プロジェクトデプロイ用)
  • Workers スクリプト (Workers Scripts) — 編集 (Edit) (WorkersスクリプトおよびCLI設定制御用)

🌐 1-2. カスタムドメイン連携およびCDNエッジキャッシュ使用段階 (今後の設定)

ブログに個人ドメインを接続し、パフォーマンス向上のためにエッジCDNキャッシュを強制的にクリア（Purge）する機能などを有効にする場合に、初めて Zoneレベルの権限が要求されます。

• 追加必須権限:
  • Zone: キャッシュパージ (Cache Purge) — 編集 (Edit) (デプロイ完了時やコンテンツ更新時にCDNエッジサーバーのキャッシュを即座に削除するために必要)
• セキュリティのベストプラクティス: トークンのスコープを制限する際、Zone Resourcesを「All Zones（すべてのゾーン）」にせず、使用している特定固有のドメイン（Zone）にスコープを限定してトークンを発行するのが安全です。
• 注意: カスタムドメインの設定方法およびキャッシュ制御メカニズムの詳細は、今後別途発行される 「カスタムドメイン設定に関する詳細説明書」 で詳しく解説する予定であるため、初期構築段階の現在は該当設定を省略して進めても問題ありません。

🛠️ 2. Cloudflare API トークンの生成手順

非対話型ログインを可能にするトークンは、Cloudflareダッシュボードで以下の手順に従って簡単に生成できます。

1. Cloudflareダッシュボードにログイン:
   • Cloudflare Dashboardにアクセスしてログインします。
2. トークン作成メニューへの移動:
   • 画面右上のプロフィールアイコンをクリックし、「マイプロフィール」 (My Profile) を選択します。
   • 左側メニューから 「API トークン」 (API Tokens) を選択します。
   • 右側の 「トークンを作成する」 (Create Token) ボタンをクリックします。
3. カスタムトークンの設定:
   • テンプレート一覧の一番下にある 「カスタムトークン」 (Create Custom Token) 領域の 「始める」 (Get Started) をクリックします。
4. 権限 (Permissions) の割り当て:
   • トークン名 (Token Name): 判別しやすい名前を入力 (例: sveltekit-blog-cli-token)
   • Permissions (アクセス許可):
     • アカウント (Account) -> D1 -> 編集 (Edit)
     • アカウント (Account) -> Workers KV ストレージ (Workers KV Storage) -> 編集 (Edit)
     • アカウント (Account) -> Cloudflare Pages -> 編集 (Edit)
     • アカウント (Account) -> Workers スクリプト (Workers Scripts) -> 編集 (Edit)
5. スコープの制限:
   • アカウントリソース (Account Resources): 含める (Include) -> 自身の Cloudflare アカウントを選択 (権限範囲を自身のアカウント内部のみに絞り、セキュリティ脅威を隔離します。)
6. 生成完了と保管:
   • 「サマリーに進む」 (Continue to summary) を押した後、「トークンを作成」 (Create Token) をクリックして生成された固有のトークン値（英数字と記号で構成された長いキー文字列）を安全な場所にコピーして保管します。 (この値は一度画面を閉じると再確認できないため、紛失した場合は再発行する必要があります。)

💻 3. 発行されたAPIトークンの適用および環境変数の設定方法

対話型のブラウザログインウィンドウを開くことができないため、システム環境変数に発行されたトークン値を挿入して、Wranglerが自動的にこれを読み込んで認証を確立するように誘導する必要があります。

3-1. OS環境別のターミナル環境変数コマンド

セットアップスクリプトを実行するターミナルコンソール画面に、OSの種類に応じて以下のコマンドを入力します。

• Linux / macOS / Git Bash (Bash/Zsh Shell):

  export CLOUDFLARE_API_TOKEN="発行された_トークン_値"
  

• Windows Command Prompt (CMD):

  set CLOUDFLARE_API_TOKEN=発行された_トークン_値
  

• Windows PowerShell:

  $env:CLOUDFLARE_API_TOKEN="発行된_トークン_値"
  

[!NOTE]
💻 macOS環境での実行および検証に関するご案内

• 本ガイドは、Windows 10/11 および Linux(Ubuntu 22.04 LTS) の物理コンソール環境で、コマンドラインの起動およびトークン連携の有効性を事前にテスト・検証済みです。
• ただし、作成者個人の検証用ハードウェアの都合上、macOS（実際のMac環境）での動作確認は実施できていません。Node.js CLIのクロスプラットフォーム動作の原則に基づき、macOSでもZsh/Bashターミナルを介して同様に export コマンドで問題なく正常に稼働すると想定されます。

3-2. ローカル開発環境ファイルおよびCI/CDの連携

• ローカル開発環境 (.dev.vars):
  ターミナルを開くたびに環境変数を入力するのが手間な場合は、apps/blog/.dev.vars および apps/admin/.dev.vars ファイルに以下のように登録しておくと、ローカルで wrangler dev を起動する際に自動的にトークンが読み込まれバインドされます。

  CLOUDFLARE_API_TOKEN="発行された_トークン_値"
  

• CI/CDパイプライン (GitHub Actions):
  GitHubリポジトリの Settings -> Secrets and variables -> Actions -> Repository secrets メニューに進み、CLOUDFLARE_API_TOKEN という名前で発行されたトークンを追加した後、YAMLワークフローファイルで以下のように呼び出して使用できます。

  - name: Build and Deploy SvelteKit Apps
    env:
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    run: npm run deploy:blog
  

🔍 4. トークンの認証状態の検証とデバッグ

トークン環境変数がシステムセッション上に正しく挿入され、バインドされているかを確認するためのデバッグコマンドです。

4-1. wrangler whoami

ターミナルで以下のコマンドを実行します。

npx wrangler whoami

• 検証成功時: 現在トークンが所属しているアカウント情報（Account Name、Account ID）およびD1、KVなどの制御権限のバインディングリストがコンソールに出力されます。
• ログインセッションのクリア (wrangler logout):
  以前にブラウザログイン方式で確立した古いセッションデータが残っており、環境変数と干渉している可能性がある場合は、先にログアウトコマンドを実行してローカルに保存されている古い認証セッションを完全に初期化してから、環境変数を再適用することをお勧めします。

  npx wrangler logout
  

⚠️ 5. よくある質問と解決策 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

• 原因: セットアップスクリプト実行中に Cloudflare の認証失敗エラーが表示される状態です。
• 解決策: 挿入した CLOUDFLARE_API_TOKEN の文字列にタイポや不要なスペースが含まれていないか確認してください。また、ダッシュボードでトークンを発行した際に指定した Account Resources スコープが、現在接続しているアカウントと一致しているか再確認してください。

🚨 2. Forbidden (アクセス拒否エラー)

• 原因: D1のマイグレーションは成功するものの、PagesのデプロイやKVリソースの生成時にアクセス拒否エラーが発生する場合です。
• 解決策: 作成したトークンのアクセス許可（Permissions）リストに Cloudflare Pages -> Edit や Workers KV Storage -> Edit など、必要なアクセス権が不足していないかダッシュボードで確認し、権限を修正・追加した後に再度環境変数の設定を試みてください。

✍️ ブログ管理画面でのウェブフォント設定と読み込み最適化の詳細説明書

本プロジェクトは、ブログの視覚的な完成度と読みやすさを高めるために、管理画面から簡単にフォントをカスタマイズできる直感的な編集ツールを提供しています。

単にフォント名を適用するだけでなく、モバイル環境やネットワーク速度が制限された環境でも、最高の読み込み速度とパフォーマンススコア（Lighthouse Performance）を維持できるように設計された特別な最適化エンジンが連動して動作します。

本説明書では、管理画面デザインエディターでの具体的なフォント設定方法と、内部的にフォントがどのように最適化されて訪問者に高速提供されるかの動作概念を詳細に解説します。

📂 1. デザインエディター内のフォント設定詳細項目

管理画面デザインエディターページの設定メニューから、ブログのレイアウトに合わせてフォントの種類、サイズ、太さを詳細に編集できます。

✍️ 1-1. グローバルウェブフォント設定 (全体ページに適用)

ブログのメイン本文領域および基本インターフェース全般にデフォルトでバインドされるグローバルフォントを管理します。

• 基本フォント設定 (Font Family):
  • ブログ全体のベースとなる本文書体を指定します。
  • 入力方法: ブラウザが認識できるフォント名を入力します。空欄のままにすると、システムデフォルトフォントである Inter がブログ全体に継承されます。（例: 'Noto Serif JP', serif または Pretendard）
• 追加するGoogleウェブフォント (Google Font Name):
  • ロゴテキストや主要なウィジェットタイトルなどの特定領域に個別に指定したいGoogleフォントの英語名を入力します。
  • 入力方法: カンマ(,)またはセミコロン(;)で区切って複数のフォントを並べて登録できます。（例: Noto Serif JP, Newsreader）
  • 連動効果: ここに入力したカスタムフォント名は、ヘッダーのロゴフォント設定や各領域の個別フォント選択オプションのドロップダウンメニューに自動的に表示され、選択可能になります。
• 基本フォントサイズ (Base Size) & 基本フォントサイズ (Base Size) (Mobile):
  • デスクトップ表示とモバイル表示それぞれの基準となる本文フォントサイズを定義します。
  • 入力方法とヒント: 16px や 14px のような**絶対単位(px)だけでなく、ユーザーのブラウザデフォルト設定に合わせて柔軟に変更される相対単位(rem, em)**形式の入力にも対応しています。（例: デスクトップ 1rem または 16px / モバイル 0.875rem または 14px）

🎨 1-2. ヘッダーおよびロゴフォント設定

上部ナビゲーションヘッダーに表示されるブランディングロゴテキストに、独立したデザインを適用します。

• フォントファミリー (Font Family):
  • ロゴテキストに適用する書体をドロップダウンから選択します。
  • デフォルト設定の フォント継承 (Inherit) を選択すると、全体のグローバルフォントを継承します。グローバルウェブフォント設定の**[追加するGoogleウェブフォント]**領域に入力したフォントがある場合、リストに自動的に表示され、個別に選択できます。
• フォントサイズ & モバイルフォントサイズ:
  • 画面サイズの変化によってロゴテキストがはみ出したり、レイアウトが崩れたりしないように、デスクトップサイズとモバイルサイズを別々に指定できます。（例: デスクトップ 1.5rem / モバイル 1.2rem）
• ロゴの太さ (Logo Weight):
  • ロゴの視覚的な存在感を調整するために、100（最も細い）から 900（最も太い）まで100単位の太さ選択オプションを提供しています。
  • 注意事項: 実際に表示される太さは、選択したフォントファミリー側の仕様に依存します。選択したウェブフォントが特定の太さ（例: 100または900）をサポートしていない場合、ブラウザはサポートされている最も近い太さに代用して表示するため、あらかじめフォントの仕様を確認しておくことをお勧めします。

🧩 1-3. グローバルウィジェットスタイル設定

サイドバーやフッター領域などに配置される個別ウィジェットカードのタイトルおよび詳細項目のテキストスタイルを調整します。

• グローバルウィジェットタイトルスタイル: 全てのウィジェットカードの上部に表示されるタイトル領域のフォントファミリー、サイズ、太さ、色を設定します。
• グローバルウィジェット項目スタイル: ウィジェットカードを構成する個別のコンテンツおよびリンクテキストに適用するスタイルを設定します。
• 継承規則: ウィジェット設定もフォントファミリー名を空欄にすると、最上位のグローバルフォントを自動的に継承し、デザインの一貫性を維持します。

⚡ 2. フォント読み込みパフォーマンスの最適化メカニズム

ウェブサイトでよく発生するフォント読み込み遅延は、パフォーマンススコアを低下させる大きな原因となります。これを防止するため、本ブログエンジンはサーバーレス環境に最適化された独自のフォント加速パイプラインを内蔵しています。

🛡️ 2-1. システム内蔵基本フォントのフィルタリング

訪問者のデバイス（PCやスマートフォン）のOSにあらかじめインストールされている可能性が高いフォント（例: Pretendard, Arial, system-ui など）については、サーバー側で自動的に除外します。これにより、不要なGoogleフォントサーバーへの通信を完全にカットし、ネットワークトラフィックを削減します。

🔄 2-2. 外部リクエストのブロックと独自プロキシ中継

一般的なウェブサイトのように、外部のGoogleフォントサーバー（fonts.googleapis.com および gstatic.com）にクライアントブラウザが直接接続すると、DNSクエリやSSL接続に時間がかかり、レン더リングの遅延が発生します。

• 中継スタイルシートの生成: ページレンダリング時にGoogleサーバーを直接呼び出す代わりに、ブログ独自のAPIを通じてスタイルシート(CSS)をプロキシ取得します。
• 内部リンクの置換: スタイルシート内の実際のフォントファイル(.woff2)のダウンロードリンクを解析し、Googleの外部URLからブログ内部の独自ドメインプロキシURLへ一括変換します。
• セキュリティフィルタ: プロキシAPIは、Google公式フォントドメイン以外のホストへの不正アクセスを遮断し、任意の有害コードの中継を安全に防止します。

💾 2-3. Cloudflare Pages CDNおよびブラウザローカルキャッシュ

プロキシ経由で要求された全てのフォント定義およびフォントファイル(.woff2)は、Cloudflareのグローバルエッジサーバー(CDN)に24時間キャッシュされます。

• また、ブラウザにも強力なキャッシュヘッダーを付与して応答するため、ユーザーが別の記事をクリックしたり、次回再訪問した際には、ネットワーク経由ではなくローカルデバイスメモリから0msで即座にフォントがレンダリングされます。これにより、フォント読み込みのずれによってレイアウトがガタつく現象(CLS)をほぼ完全に防止します。

🚀 2-4. Pretendardフォント特化加速の適用

日本語・韓国語の可読性に最適化されたシステム書体である Pretendard をグローバルフォントとして使用する場合、レンダリング速度を劇的に短縮する迂回加速ルートが自動的に開通します。

• 並行ダウンロードの相乗効果: Googleサーバーや中継プロキシAPIを経由せず、世界中にエッジが配置された超高速オープンソースCDN（jsDelivr）静的ネットワークを通じて、他のスクリプトと並行してフォントファイルをロードします。
• レンダリングの最適化: 容量の大きい東アジア言語フォントを最短時間で確保し、初回のページ進入時に文字の表示が遅れたり、途中でフォントが急に切り替わったりする現象を回避します。

💡 3. 設定時の注意事項と推奨値

[!IMPORTANT]
💡 管理画面でフォントを変更する際の3つの行動規則

1. Googleウェブフォント名の正確なスペル遵守:
   • 追加するGoogleウェブフォント項目に入力する英語名は、Google Fontsライブラリの公式英字表記と100%同一である必要があります。スペルミスや不要なスペースがあるとローダーがフォントを認識できず、代替フォント（Sans-serif）で強制表示されます。
2. デスクトップとモバイルのフォントサイズバランスの調整:
   • モバイル表示でもデスクトップのフォントサイズをそのまま適用すると、画面の可読性が低下します。モバイルフォントサイズ項目には、基準より 2px 程度小さいサイズを個別に指定して、レスポンシブデザインを適切に維持してください。
3. 安定した日本語フォールバック(Fallback)フォントの宣言:
   • 本文のフォント設定にカスタムウェブフォントを適用する際、'Noto Serif JP', serif のように、末尾にシステムの汎用代替名（serif または sans-serif）を並べて指定することで、ウェブフォントのロードが一時的に遅延した瞬間でも、テキストが崩れずにフォールバックフォントで安定して描画されます。