sveltia-cms

Sveltia CMS スキル

静的サイトプロジェクトに Sveltia CMS を統合するための包括的なスキルです。

---

Sveltia CMS とは？

Sveltia CMS は、Decap CMS（旧 Netlify CMS）の現代的な後継としてゼロから構築された、Git ベースの軽量なヘッドレスコンテンツ管理システムです。Git リポジトリに保存されたコンテンツを、すばやく直感的に編集できるインターフェースを提供します。

主な機能

1. 軽量で高速

   • バンドルサイズ：<500 KB（圧縮・brotlied）で、競合製品の 1.5-2.6 MB より小さい
   • Svelte コンパイラーを使用して構築（仮想 DOM によるオーバーヘッドなし）
   • GraphQL API を使用してコンテンツを即座に取得
   • すべてのコンテンツを対象に関連度ベースで検索

2. モダンなユーザー体験

   • ビューポート全体を活用する直感的な管理インターフェース
   • ダークモード対応（システム設定に従います）
   • モバイルとタブレットに最適化
   • 複数ファイルに対応したドラッグ＆ドロップでのファイルアップロード
   • 即時更新されるリアルタイムプレビュー

3. Git ネイティブなアーキテクチャ

   • コンテンツを Markdown、MDX、YAML、TOML、または JSON として保存
   • 完全なバージョン管理と変更履歴
   • ベンダーロックインなし — コンテンツはコードとともに保存
   • GitHub、GitLab、Gitea、Forgejo のバックエンドに対応

4. フレームワークに依存しない

   • バニラ JavaScript バンドルとして配信
   • Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit で動作
   • React、Vue、フレームワークのランタイム依存なし
   • あらゆる静的サイトジェネレーターと互換性あり

5. 多言語化を標準搭載

   • 複数言語への対応を標準搭載
   • ワンクリックで DeepL 翻訳を連携
   • 編集中にロケールを切り替え
   • 柔軟な i18n 構造（ファイル、フォルダー、単一ファイル）

6. 画像最適化機能を標準搭載

   • WebP への自動変換
   • クライアント側でのサイズ変更と最適化
   • SVG 最適化に対応
   • 品質とサイズを設定可能

現在のバージョン

• @sveltia/cms: 0.113.5（2025年10月）
• ステータス: パブリックベータ（v1.0 は 2026年初頭にリリース予定）
• 成熟度: 本番環境で利用可能（前身から 265 件以上の問題を解決）

---

このスキルを使う場合

✅ Sveltia CMS を使う場面：

1. 静的サイトを構築する

   • Hugo のブログやドキュメント
   • Jekyll サイトや GitHub Pages
   • 11ty（Eleventy）プロジェクト
   • Gatsby のマーケティングサイト
   • コンテンツの多い Astro サイト

2. 技術に詳しくない編集者がアクセスする必要がある

   • ページを管理するマーケティングチーム
   • ブログ記事を執筆する著者
   • Git の知識がないコンテンツチーム
   • コンテンツを簡単に更新したいクライアント

3. Git ベースのワークフローが望ましい

   • Git によるコンテンツのバージョン管理
   • プルリクエストによるコンテンツレビュー
   • リポジトリ内でコンテンツをコードとともに管理
   • デプロイのための CI/CD 連携

4. 軽量なソリューションが必要

   • パフォーマンスが重視されるプロジェクト
   • モバイルファーストの編集が必要
   • 高速な読み込みが重要
   • 最小限のバンドルサイズが重要

5. Decap/Netlify CMS から移行する

   • 既存の config.yml を再利用可能
   • そのまま置き換え可能（1 行を変更）
   • パフォーマンスと UX が向上
   • 積極的なメンテナンスとバグ修正

❌ Sveltia CMS を使わない場面：

1. リアルタイムの共同編集が必要

   • 複数ユーザーが同時に編集する（Google Docs のような形式）
   • 代わりに Sanity、Contentful、または TinaCMS を使用

2. ビジュアルなページ作成が必要

   • ドラッグ＆ドロップ式のページビルダーが必要
   • 代わりに Webflow、Builder.io、または TinaCMS（React）を使用

3. 高度に動的なデータを扱う

   • リアルタイムの在庫管理を伴う E コマース
   • リアルタイムのダッシュボードや分析
   • 代わりに従来型のデータベース（D1、PostgreSQL）を使用

4. React 固有のビジュアル編集が必要

   • コンテキスト内でのコンポーネント編集
   • 代わりに TinaCMS を使用（React に特化）

Sveltia CMS と TinaCMS の比較

次の場合は Sveltia を使用します。

• Hugo、Jekyll、11ty、Gatsby（React を使用しない SSG）
• 従来型の CMS 管理パネルの UX
• 軽量なバンドルが必要な場合
• フレームワークに依存しないプロジェクト

次の場合は TinaCMS を使用します。

• React、Next.js、Astro（React コンポーネント）
• コンテキスト内でのビジュアル編集
• スキーマ駆動の型安全なコンテンツ
• TypeScript による最新の開発者エクスペリエンス

どちらも有効な選択肢です。Sveltia CMS は、用途に応じて TinaCMS を補完します。

---

フレームワーク別のセットアップパターン

使用するフレームワークに応じて、適切なセットアップパターンを選択してください。

1. Hugo のセットアップ（最も一般的）

Hugo は、Sveltia CMS で最もよく使われている静的サイトジェネレーターです。

手順：

1. 管理ディレクトリを作成します：

   mkdir -p static/admin
   

2. 管理用のインデックスページを作成します：

   
   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Content Manager</title>
     </head>
     <body>
       <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
     </body>
   </html>
   

3. 設定ファイルを作成します：

   # static/admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   media_folder: static/images/uploads
   public_folder: /images/uploads
   
   collections:
     - name: posts
       label: Blog Posts
       folder: content/posts
       create: true
       slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
       fields:
         - { label: 'Title', name: 'title', widget: 'string' }
         - { label: 'Date', name: 'date', widget: 'datetime' }
         - { label: 'Draft', name: 'draft', widget: 'boolean', default: true }
         - { label: 'Tags', name: 'tags', widget: 'list', required: false }
         - { label: 'Body', name: 'body', widget: 'markdown' }
   

4. Hugo の開発サーバーを起動します：

   hugo server
   

5. 管理画面にアクセスします：

   http://localhost:1313/admin/
   

テンプレート：templates/hugo/ を参照してください。

---

2. Jekyll のセットアップ

Jekyll は、GitHub Pages と Sveltia CMS の組み合わせでよく使われています。

手順：

1. 管理ディレクトリを作成します：

   mkdir -p admin
   

2. 管理用のインデックスページを作成します：

   
   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Content Manager</title>
     </head>
     <body>
       <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
     </body>
   </html>
   

3. 設定ファイルを作成します：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   media_folder: assets/images/uploads
   public_folder: /assets/images/uploads
   
   collections:
     - name: posts
       label: Blog Posts
       folder: _posts
       create: true
       slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
       fields:
         - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' }
         - { label: 'Title', name: 'title', widget: 'string' }
         - { label: 'Date', name: 'date', widget: 'datetime' }
         - { label: 'Categories', name: 'categories', widget: 'list', required: false }
         - { label: 'Body', name: 'body', widget: 'markdown' }
   

4. Jekyll の開発サーバーを起動します：

   bundle exec jekyll serve
   

5. 管理画面にアクセスします：

   http://localhost:4000/admin/
   

テンプレート：templates/jekyll/ を参照してください。

---

3. 11ty（Eleventy）のセットアップ

11ty は、柔軟な静的サイトを構築する際に Sveltia CMS とよく連携します。

手順：

1. 管理ディレクトリを作成します：

   mkdir -p admin
   

2. 管理用のインデックスページを作成します：

   
   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Content Manager</title>
     </head>
     <body>
       <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
     </body>
   </html>
   

3. 設定ファイルを作成します：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   media_folder: src/assets/images
   public_folder: /assets/images
   
   collections:
     - name: blog
       label: Blog Posts
       folder: src/posts
       create: true
       slug: '{{slug}}'
       fields:
         - { label: 'Title', name: 'title', widget: 'string' }
         - { label: 'Description', name: 'description', widget: 'text' }
         - { label: 'Date', name: 'date', widget: 'datetime' }
         - { label: 'Tags', name: 'tags', widget: 'list', required: false }
         - { label: 'Body', name: 'body', widget: 'markdown' }
   

4. .eleventy.js にパススルーコピーを追加します：

   module.exports = function(eleventyConfig) {
     eleventyConfig.addPassthroughCopy('admin');
     // ... rest of config
   };
   

5. 11ty の開発サーバーを起動します：

   npx @11ty/eleventy --serve
   

6. 管理画面にアクセスします：

   http://localhost:8080/admin/
   

テンプレート：templates/11ty/ を参照してください。

---

4. Astro のセットアップ

Astro は、Sveltia CMS とよく連携するモダンなフレームワークです。

手順：

1. 管理ディレクトリを作成します：

   mkdir -p public/admin
   

2. 管理用のインデックスページを作成します：

   
   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Content Manager</title>
     </head>
     <body>
       <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
     </body>
   </html>
   

3. 設定ファイルを作成します：

   # public/admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   media_folder: public/images
   public_folder: /images
   
   collections:
     - name: blog
       label: Blog Posts
       folder: src/content/blog
       create: true
       slug: '{{slug}}'
       format: mdx
       fields:
         - { label: 'Title', name: 'title', widget: 'string' }
         - { label: 'Description', name: 'description', widget: 'text' }
         - { label: 'Published Date', name: 'pubDate', widget: 'datetime' }
         - { label: 'Hero Image', name: 'heroImage', widget: 'image', required: false }
         - { label: 'Body', name: 'body', widget: 'markdown' }
   

4. Astro の開発サーバーを起動します：

   npm run dev
   

5. 管理画面にアクセスします：

   http://localhost:4321/admin/
   

テンプレート：templates/astro/ を参照してください。

---

5. フレームワークに依存しないセットアップ

対象：Gatsby、Next.js（SSG モード）、SvelteKit、Remix、またはその他のフレームワーク

手順：

1. 公開ディレクトリを確認します：

   • Gatsby：static/
   • Next.js：public/
   • SvelteKit：static/
   • Remix：public/

2. 公開フォルダー内に管理ディレクトリを作成します：

   mkdir -p <public-folder>/admin
   

3. 管理用のインデックスページを作成します：

   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Content Manager</title>
     </head>
     <body>
       <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
     </body>
   </html>
   

4. コンテンツ構造に合わせて設定ファイルを作成します：

   backend:
     name: github
     repo: owner/repo
     branch: main
   
   media_folder: <your-media-path>
   public_folder: <your-public-path>
   
   collections:
     # Define based on your content structure
   

5. 管理画面にアクセスします：

   http://localhost:<port>/admin/
   

---

認証のセットアップ

デプロイ先のプラットフォームに適した認証方法を選択してください。

オプション 1：Cloudflare Workers OAuth（推奨）🔥

最適な用途：Cloudflare Pages、Cloudflare Workers、その他のデプロイ先

公式の sveltia-cms-auth Cloudflare Worker を使って OAuth を実装します。

手順：

1. Worker をデプロイします：

   # Clone the auth worker
   git clone https://github.com/sveltia/sveltia-cms-auth
   cd sveltia-cms-auth
   
   # Install dependencies
   npm install
   
   # Deploy to Cloudflare Workers
   npx wrangler deploy
   

   または、ワンクリックでデプロイします：

   • https://github.com/sveltia/sveltia-cms-auth にアクセスします
   • 「Deploy to Cloudflare Workers」ボタンをクリックします

2. GitHub で OAuth アプリを登録します：

   • https://github.com/settings/developers にアクセスします
   • 「New OAuth App」をクリックします
   • アプリケーション名：サイト名 CMS
   • ホームページ URL：https://yourdomain.com
   • 認証コールバック URL：https://your-worker.workers.dev/callback
   • クライアント ID とクライアントシークレットを保存します

3. Worker の環境変数を設定します：

   # Set GitHub credentials
   npx wrangler secret put GITHUB_CLIENT_ID
   # Paste your Client ID
   
   npx wrangler secret put GITHUB_CLIENT_SECRET
   # Paste your Client Secret
   
   # Optional: Restrict to specific domains
   npx wrangler secret put ALLOWED_DOMAINS
   # Example: yourdomain.com,*.yourdomain.com
   

4. CMS の設定を更新します：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
     base_url: https://your-worker.workers.dev  # ← Add this line
   

5. 認証をテストします：

   • サイトの /admin/ を開きます
   • 「Login with GitHub」をクリックします
   • アプリを承認します
   • CMS にリダイレクトされます

詳しい手順：references/cloudflare-auth-setup.md を参照してください。

テンプレート：templates/cloudflare-workers/ を参照してください。

---

オプション 2：Vercel Serverless Functions

最適な用途：Vercel へのデプロイ

手順：

1. API ルートを作成します：

   // api/auth.ts
   export default async function handler(req, res) {
     // OAuth handling logic
     // See templates/vercel-serverless/api-auth.ts
   }
   

2. Vercel で環境変数を設定します：

   GITHUB_CLIENT_ID=your_client_id
   GITHUB_CLIENT_SECRET=your_client_secret
   

3. CMS の設定を更新します：

   backend:
     name: github
     repo: owner/repo
     branch: main
     base_url: https://yourdomain.com/api/auth
   

テンプレート：templates/vercel-serverless/ を参照してください。

---

オプション 3：Netlify Functions（推奨しません）

注：Sveltia CMS は、パフォーマンス上の理由から Git Gateway のサポートを意図的に省いています。

Netlify にデプロイする場合は、次のいずれかを使用してください。

• Cloudflare Workers OAuth（推奨。より高速です）
• カスタム OAuth を使用した Netlify Functions（Vercel のパターンと同様）

---

オプション 4：ローカル開発（GitHub/GitLab 直接接続）

ローカル開発専用 — 認証プロキシは不要です。

要件：

• GitHub/GitLab の個人用アクセストークン
• File System Access API に対応したブラウザー（Chrome、Edge）

セットアップ：

1. 個人用アクセストークンを生成します。

   • GitHub：https://github.com/settings/tokens
   • スコープ：repo（プライベートリポジトリへの完全なアクセス権）

2. ローカルバックエンドを設定します。

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   local_backend: true  # Enable local mode
   

3. Sveltia のローカルリポジトリ機能を使用します。

   • ログイン画面で「ローカルリポジトリで作業」をクリックします
   • ローカルの Git リポジトリフォルダーを選択します
   • 変更はローカルファイルに直接保存されます
   • Git を使って手動でコミットし、プッシュします

注：これは開発専用です。本番環境では OAuth プロキシが必要です。

---

設定のベストプラクティス

基本的な設定構造

# admin/config.yml

# Backend (Git provider)
backend:
  name: github  # or gitlab, gitea, forgejo
  repo: owner/repo
  branch: main
  base_url: https://your-auth-worker.workers.dev  # OAuth proxy

# Media storage
media_folder: static/images/uploads  # Where files are saved
public_folder: /images/uploads        # URL path in content

# Optional: Multiple media libraries
media_libraries:
  default:
    config:
      max_file_size: 5242880  # 5 MB in bytes
      slugify_filename: true
      transformations:
        raster_image:
          format: webp
          quality: 85
          width: 2048
          height: 2048
        svg:
          optimize: true

# Optional: Custom branding
logo_url: https://yourdomain.com/logo.svg

# Collections (content types)
collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      # Field definitions

---

コレクションのパターン

コレクションでは、コンテンツの種類と保存先を定義します。

ブログ投稿コレクション

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
    format: yaml  # or md, toml, json
    fields:
      - label: Title
        name: title
        widget: string

      - label: Date
        name: date
        widget: datetime
        date_format: 'YYYY-MM-DD'
        time_format: false  # Date only

      - label: Draft
        name: draft
        widget: boolean
        default: true

      - label: Featured Image
        name: image
        widget: image
        required: false

      - label: Excerpt
        name: excerpt
        widget: text
        required: false

      - label: Tags
        name: tags
        widget: list
        required: false

      - label: Body
        name: body
        widget: markdown

テンプレート：templates/collections/blog-posts.ymlを参照してください。

---

ドキュメントページコレクション

collections:
  - name: docs
    label: Documentation
    folder: content/docs
    create: true
    slug: '{{slug}}'
    format: mdx
    fields:
      - label: Title
        name: title
        widget: string

      - label: Description
        name: description
        widget: text

      - label: Order
        name: order
        widget: number
        value_type: int
        hint: Sort order in sidebar

      - label: Category
        name: category
        widget: select
        options:
          - Getting Started
          - API Reference
          - Tutorials
          - Advanced

      - label: Body
        name: body
        widget: markdown

テンプレート：templates/collections/docs-pages.ymlを参照してください。

---

ランディングページコレクション（構造化コンテンツ）

collections:
  - name: pages
    label: Landing Pages
    folder: content/pages
    create: true
    slug: '{{slug}}'
    format: json
    fields:
      - label: Title
        name: title
        widget: string

      - label: SEO
        name: seo
        widget: object
        fields:
          - { label: Meta Title, name: metaTitle, widget: string }
          - { label: Meta Description, name: metaDescription, widget: text }
          - { label: OG Image, name: ogImage, widget: image }

      - label: Hero Section
        name: hero
        widget: object
        fields:
          - { label: Headline, name: headline, widget: string }
          - { label: Subheadline, name: subheadline, widget: text }
          - { label: Hero Image, name: image, widget: image }
          - label: CTA Button
            name: cta
            widget: object
            fields:
              - { label: Text, name: text, widget: string }
              - { label: URL, name: url, widget: string }

      - label: Features
        name: features
        widget: list
        fields:
          - { label: Title, name: title, widget: string }
          - { label: Description, name: description, widget: text }
          - { label: Icon, name: icon, widget: image }

テンプレート：templates/collections/landing-pages.ymlを参照してください。

---

国際化（i18n）のセットアップ

Sveltia CMS は、複数の構造オプションで i18n を標準でサポートしています。

複数ファイル構造（推奨）

最適な用途：Hugo、ロケールごとにファイルを分ける Jekyll

i18n:
  structure: multiple_files
  locales: [en, fr, de, ja]
  default_locale: en

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    i18n: true  # Enable i18n for this collection
    fields:
      - label: Title
        name: title
        widget: string
        i18n: true  # Translatable field

      - label: Date
        name: date
        widget: datetime
        i18n: duplicate  # Same value across locales

      - label: Body
        name: body
        widget: markdown
        i18n: true

結果：次のようなファイルが作成されます。

• content/posts/hello-world.en.md
• content/posts/hello-world.fr.md
• content/posts/hello-world.de.md

---

複数フォルダー構造

最適な用途：ロケールディレクトリを使う Next.js、Astro

i18n:
  structure: multiple_folders
  locales: [en, fr, de]
  default_locale: en

collections:
  - name: blog
    label: Blog Posts
    folder: content/{{locale}}/blog  # {{locale}} placeholder
    create: true
    i18n: true
    fields:
      # Same as above

結果：次のようなファイルが作成されます。

• content/en/blog/hello-world.md
• content/fr/blog/hello-world.md
• content/de/blog/hello-world.md

---

単一ファイル構造

最適な用途：1 つのファイルで翻訳を管理する i18n ライブラリ

i18n:
  structure: single_file
  locales: [en, fr, de]
  default_locale: en

collections:
  - name: translations
    label: Translations
    files:
      - name: ui
        label: UI Strings
        file: data/translations.json
        i18n: true
        fields:
          - label: Navigation
            name: nav
            widget: object
            i18n: true
            fields:
              - { label: Home, name: home, widget: string, i18n: true }
              - { label: About, name: about, widget: string, i18n: true }

参考資料：完全なガイドについてはreferences/i18n-patterns.mdを参照してください。

---

DeepL 翻訳の統合

Sveltia CMS には、ワンクリックで翻訳できる機能が DeepL を使って組み込まれています。

セットアップ：

1. DeepL API キーを取得します。

   • https://www.deepl.com/pro-api で登録します
   • 無料プラン：月 500,000 文字

2. 設定に追加します。

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
   
   i18n:
     structure: multiple_files
     locales: [en, fr, de, es, ja]
     default_locale: en
   
   # DeepL integration
   deepl:
     api_key: your-deepl-api-key
     # Or use environment variable: DEEPL_API_KEY
   

3. エディターで使用します。

   • デフォルト以外のロケールに切り替えます
   • 「[デフォルトロケール]から翻訳」ボタンをクリックします
   • DeepL が翻訳可能なすべてのフィールドをすぐに翻訳します

注：翻訳の品質は DeepL の AI によって異なるため、翻訳内容は必ず確認してください。

---

よくあるエラーと解決策

このスキルは、Sveltia CMS のセットアップ時によく発生する8 つのエラーを防ぎます。

1. ❌ OAuth 認証の失敗

エラーメッセージ：

• 「エラー：認証に失敗しました」
• GitHub のログイン画面ではなく、https://api.netlify.com/authにリダイレクトされる

症状：

• ログインボタンをクリックしても何も起きない
• 正しくないドメインにリダイレクトされる
• 認証ポップアップがすぐに閉じる

原因：

• バックエンド設定にbase_urlがない
• OAuth プロキシの URL が正しくない
• CORS ポリシーによって認証がブロックされている
• GitHub OAuth コールバック URL が正しくない

解決策：

手順 1：config.yml にbase_urlがあることを確認します。

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev  # ← Must be present

手順 2：GitHub OAuth App のコールバックを確認します。

• 次の URL である必要があります：https://your-worker.workers.dev/callback
• 次の URL ではありません：https://yourdomain.com/callback

手順 3：Worker の環境変数を確認します。

npx wrangler secret list
# Should show: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET

手順 4：Worker を直接テストします。

curl https://your-worker.workers.dev/health
# Should return: {"status": "ok"}

予防策：

• GitHub の直接認証を使用しない場合は、必ずbase_urlを設定します
• シークレットウィンドウで OAuth フローをテストします
• ブラウザーコンソールで CORS エラーを確認します

---

2. ❌ TOML フロントマターのエラー

エラーメッセージ:

• 「解析エラー: 無効な TOML です」
• +++ 区切り文字がないファイル
• 本文の内容がフロントマターに表示される

症状:

• CMS で新規作成したファイルを Hugo で解析できない
• 編集後に既存の TOML ファイルが壊れる
• 本文の区切りより前にコンテンツが表示される

原因:

• ベータ版の Sveltia に TOML 生成の不具合がある
• TOML 区切り文字の処理が不完全
• 同じコレクション内で TOML と YAML が混在している

解決策:

TOML ではなく YAML を使用する（推奨）:

collections:
  - name: posts
    folder: content/posts
    format: yaml  # or md (Markdown with YAML frontmatter)
    # NOT: format: toml

TOML を使用する必要がある場合:

1. CMS の保存後に区切り文字を手動で修正します
2. TOML を検証する pre-commit フックを使用します
3. ベータ版の修正を待ちます（GitHub のイシューを確認します）

TOML から YAML への移行:

# Convert all posts from TOML to YAML
for file in content/posts/*.md; do
  # Use Hugo's built-in converter
  hugo convert toYAML "$file"
done

予防策:

• 新しいプロジェクトでは YAML 形式を優先します
• Hugo で TOML が必要な場合は、本番環境に導入する前に CMS を十分にテストします
• TOML の修正について、Sveltia の GitHub リリースを確認します

---

3. ❌ YAML 解析エラー

エラーメッセージ:

• 「YAML 解析エラー: 無効な YAML です」
• 「エラー: 重複したキー 'field_name'」
• 「位置 X に予期しない文字があります」

症状:

• 既存の投稿を CMS で読み込めない
• コンテンツの変更を保存できない
• CMS に空のフィールドが表示される

原因:

• Sveltia は YAML の書式について Hugo/Jekyll より厳格です
• 1 つのファイルに複数の YAML ドキュメントがある（---\n---\n---）
• インデントや特殊文字が正しくない
• コピー＆ペーストによるスマートクォート

解決策:

ステップ 1: YAML を検証します:

# Install yamllint
pip install yamllint

# Check all content files
find content -name "*.md" -exec yamllint {} \;

ステップ 2: よくある問題を修正します:

問題: 1 つのファイルに複数のドキュメントがある

---
title: Post 1
---
---  # ← Remove this extra separator
title: Post 2
---

問題: インデントが正しくない

# ❌ Bad - inconsistent indentation
fields:
  - name: title
     label: Title  # Extra space
  - name: date
    label: Date

# ✅ Good - consistent 2-space indentation
fields:
  - name: title
    label: Title
  - name: date
    label: Date

問題: スマートクォート

# ❌ Bad - smart quotes from copy-paste
title: "Hello World"  # Curly quotes

# ✅ Good - straight quotes
title: "Hello World"  # Straight quotes

ステップ 3: yamlfmt で自動修正します:

# Install
go install github.com/google/yamlfmt/cmd/yamlfmt@latest

# Fix all files
find content -name "*.md" -exec yamlfmt {} \;

予防策:

• YAML 対応エディターを使用します（YAML 拡張機能を備えた VS Code など）
• YAML スキーマ検証を有効にします
• pre-commit フックで yamllint を実行します

---

4. ❌ CMS にコンテンツが一覧表示されない

エラーメッセージ:

• 「エントリーが見つかりません」
• コンテンツ一覧が空
• 「エントリーの読み込みに失敗しました」

症状:

• 管理画面は読み込まれるが、コンテンツが表示されない
• コレクションが空に見える
• リポジトリにファイルがあるのに、CMS に認識されない

原因:

• 形式の不一致（設定では TOML を想定しているが、ファイルは YAML）
• フォルダーのパスが正しくない
• ファイル拡張子が形式と一致していない
• Git バックエンドが接続されていない

解決策:

ステップ 1: フォルダーのパスが実際のファイルと一致することを確認します:

# Config says:
collections:
  - name: posts
    folder: content/posts  # Expects files here

# Check actual location:
ls -la content/posts  # Files must exist here

ステップ 2: 形式を実際のファイルに合わせます:

# If files are: content/posts/hello.md with YAML frontmatter
collections:
  - name: posts
    folder: content/posts
    format: yaml  # or md (same as yaml for .md files)

# If files are: content/posts/hello.toml
collections:
  - name: posts
    folder: content/posts
    format: toml
    extension: toml

ステップ 3: ファイル拡張子を確認します:

# Config expects .md files
ls content/posts/*.md  # Should show files

# If files have different extension:
# Either rename files OR set extension in config

ステップ 4: Git バックエンドの接続を確認します:

backend:
  name: github
  repo: owner/repo  # Must be correct owner/repo
  branch: main      # Must be correct branch

予防策:

• folder のパスはリポジトリのルートからの相対パスにします
• format を実際のファイル形式に合わせます
• コレクションを作成する前に、まず 1 つのファイルでテストします

---

5. ❌ 「SVELTIA is not defined」エラー

エラーメッセージ:

• コンソールエラー: Uncaught ReferenceError: SVELTIA is not defined
• 管理画面が真っ白になる
• 管理画面の読み込みが止まる

症状:

• 管理画面は読み込まれるが、白い画面が表示される
• ブラウザーのコンソールに JavaScript エラーが表示される
• CMS が初期化されない

原因:

• script タグが正しくない
• CDN の障害またはブロック
• スクリプト URL が正しくない
• type="module" 属性がない

解決策:

ステップ 1: 正しい script タグを使用します:

<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>


<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>


<script src="https://unpkg.com/sveltia-cms/dist/sveltia-cms.js" type="module"></script>

ステップ 2: CDN にアクセスできることを確認します:

# Test CDN URL
curl -I https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js
# Should return: 200 OK

ステップ 3: バージョンを固定します（任意ですが推奨）:

<script src="https://unpkg.com/@sveltia/[email protected]/dist/sveltia-cms.js" type="module"></script>

ステップ 4: CSP によるブロックを確認します:

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' https://unpkg.com;
  style-src 'self' 'unsafe-inline' https://unpkg.com;
  connect-src 'self' https://api.github.com https://your-worker.workers.dev;
">

予防策:

• Sveltia のドキュメントにある公式 script タグをコピーして貼り付けます
• 本番環境では特定のバージョンに固定します
• 異なるブラウザーで管理画面をテストします

---

6. ❌ /admin で 404 が発生する

エラーメッセージ：

• /admin/ にアクセスすると「404 Not Found」と表示される
• 管理ページが存在しない

症状：

• サイトは読み込めるが、/admin/ は 404 を返す
• ローカルでは動作するが、本番環境では動作しない
• ファイルは存在するが、配信されない

原因：

• 管理ディレクトリが public/static フォルダーにない
• 管理ファイルがデプロイされていない
• ビルド設定が正しくない
• フレームワークが管理ファイルをコピーしていない

解決方法：

手順 1：管理ディレクトリの場所を確認します：

Hugo：static/admin/ Jekyll：admin/ 11ty：admin/（パススルーコピーを設定） Astro：public/admin/ Next.js：public/admin/ Gatsby：static/admin/

手順 2：ファイルの存在を確認します：

ls -la static/admin/  # Hugo example
# Should show: index.html, config.yml

手順 3：フレームワークごとの修正方法：

Hugo：static/ 内のファイルは自動的にコピーされます

Jekyll：_config.yml に追加します：

include:
  - admin

11ty：.eleventy.js に追加します：

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy('admin');
};

Astro：public/ 内のファイルは自動的にコピーされます

手順 4：デプロイを確認します：

# After build, check output directory
ls -la public/admin/  # or _site/admin/ or dist/admin/

予防策：

• デプロイ前に管理ページにアクセスできることをテストする
• 管理ディレクトリをバージョン管理に追加する
• プロジェクトの README に管理ページのパスを記載する

---

7. ❌ 画像をアップロードできない（HEIC 形式）

エラーメッセージ：

• 「Unsupported file format」
• 「Failed to upload image」
• 画像は表示されるが、保存されない

症状：

• iPhone の写真をアップロードできない
• HEIC ファイルが拒否される
• JPEG/PNG のみ使用できる

原因：

• ブラウザーが HEIC 形式をサポートしていない
• 画像が大きすぎる（max_file_size を超えている）
• メディアフォルダーのパスが正しくない

解決方法：

手順 1：HEIC を JPEG に変換します：

Mac の場合：

# Convert single file
sips -s format jpeg image.heic --out image.jpg

# Batch convert
for f in *.heic; do sips -s format jpeg "$f" --out "${f%.heic}.jpg"; done

iPhone の場合：

• 設定 > カメラ > フォーマット > 互換性優先
• これにより、写真は HEIC ではなく JPEG で保存されます

またはオンラインコンバーターを使用します：https://heic.to/

手順 2：画像の最適化を有効にして自動変換します：

# admin/config.yml
media_libraries:
  default:
    config:
      max_file_size: 10485760  # 10 MB
      transformations:
        raster_image:
          format: webp  # Auto-converts to WebP
          quality: 85
          width: 2048
          height: 2048

手順 3：必要に応じて最大ファイルサイズを増やします：

media_libraries:
  default:
    config:
      max_file_size: 10485760  # 10 MB in bytes
      # Default is often 5 MB

予防策：

• コンテンツ編集者向けに画像の要件を記載する
• 設定で自動最適化を有効にする
• 適切な max_file_size を設定する（5～10 MB）

---

8. ❌ CORS / COOP ポリシーエラー

エラーメッセージ：

• 「Authentication Aborted」
• 「Cross-Origin-Opener-Policy blocked」
• 認証ポップアップがすぐに閉じる

症状：

• OAuth ポップアップが開いてすぐに閉じる
• GitHub ログインを完了できない
• コンソールに COOP エラーが表示される

原因：

• 厳格な Cross-Origin-Opener-Policy ヘッダー
• CORS ヘッダーによって認証がブロックされている
• CSP によってスクリプトの実行がブロックされている

解決方法：

手順 1：COOP ヘッダーを調整します：

Cloudflare Pages（_headers ファイル）：

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups
  # NOT: same-origin (this breaks OAuth)

Netlify（_headers ファイル）：

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups

Vercel（vercel.json）：

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin-allow-popups"
        }
      ]
    }
  ]
}

手順 2：CSP に OAuth プロキシを追加します：

<meta http-equiv="Content-Security-Policy" content="
  connect-src 'self' https://api.github.com https://your-worker.workers.dev;
">

手順 3：Cloudflare Pages の場合、API アクセスを許可します：

# admin/config.yml (if using Cloudflare Pages webhooks)
# Add to CSP: https://api.cloudflare.com

予防策：

• デフォルトで COOP ヘッダーを same-origin-allow-popups に設定する
• さまざまなブラウザーで認証をテストする
• プロジェクトの README に必要なヘッダーを記載する

---

Decap CMS からの移行

Sveltia CMS は Decap CMS（旧 Netlify CMS）のドロップイン置換です。

移行手順

手順 1：script タグを更新します：

<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>


<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>

手順 2：既存の config.yml をそのまま使用します：

# Your existing Decap config.yml works as-is!
backend:
  name: github
  repo: owner/repo

collections:
  # ... no changes needed

手順 3：ローカルでテストします：

# Start your site's dev server
hugo server  # or jekyll serve, or npm run dev

# Visit /admin/ and test:
# - Login
# - Content listing
# - Editing
# - Saving
# - Media uploads

手順 4：デプロイします：

git add static/admin/index.html  # or your admin path
git commit -m "Migrate to Sveltia CMS"
git push

これだけです！ コンテンツ、コレクション、ワークフローは変更されません。

---

何が異なりますか？

設定の互換性：100% 互換

UI の変更点：

• より高速なインターフェース（仮想 DOM なし）
• モバイルでの操作性向上
• ダークモード対応
• 検索機能の改善

パフォーマンスの向上：

• バンドルサイズが 5 分の 1（300 KB 対 1.5 MB）
• コンテンツを即座に読み込み（GraphQL）
• API のレート制限の問題なし

新機能：

• DeepL 翻訳との統合
• 画像最適化を標準搭載
• UUID スラッグの生成
• i18n サポートの強化

未対応：

• Git Gateway バックエンド（パフォーマンス上の理由）
• Azure バックエンド（後日追加される可能性があります）
• Bitbucket バックエンド（後日追加される可能性があります）

回避策：代わりに Cloudflare Workers または Vercel OAuth プロキシを使用してください。

---

テストチェックリスト

完全に移行する前に、次のワークフローをテストしてください。

• OAuth でログインする
• コンテンツ一覧を表示する
• 新しいエントリーを作成する
• 既存のエントリーを編集する
• 画像をアップロードする
• 公開／非公開を切り替える
• コンテンツを検索する
• コレクションを切り替える
• モバイルで編集する（該当する場合）
• i18n を切り替える（該当する場合）

---

完全なガイド：references/migration-from-decap.md を参照してください。

---

デプロイパターン

Cloudflare Pages

最適な用途：Cloudflare エコシステムを利用した静的サイト

手順：

1. Git リポジトリを Cloudflare Pages に接続します：

   • Dashboard > Pages > Create Project
   • GitHub／GitLab に接続します
   • リポジトリを選択します

2. ビルド設定を構成します：

   Build command: hugo  # or jekyll build, or npm run build
   Build output directory: public  # or _site, or dist
   Root directory: /
   

3. OAuth Worker をデプロイします（Cloudflare Workers OAuth セクションを参照）

4. Worker の URL を config.yml に設定します：

   backend:
     base_url: https://your-worker.workers.dev
   

5. デプロイします：

   • main ブランチにプッシュします
   • Cloudflare Pages が自動的にビルドします
   • 管理画面にアクセスします：https://yourdomain.pages.dev/admin/

---

Vercel

最適な用途：Next.js、Astro、または Vercel でデプロイするあらゆるフレームワーク

手順：

1. Git リポジトリを接続します：

   • Dashboard > Add New Project
   • リポジトリをインポートします

2. ビルドを構成します：

   Framework Preset: <Auto-detected>
   Build Command: <Default>
   Output Directory: <Default>
   

3. OAuth サーバーレス関数をデプロイします（Vercel セットアップセクションを参照）

4. 環境変数を設定します：

   GITHUB_CLIENT_ID=your_client_id
   GITHUB_CLIENT_SECRET=your_client_secret
   

5. デプロイします：

   • main ブランチにプッシュします
   • Vercel が自動的にビルドします

---

Netlify

最適な用途：JAMstack サイト、従来の Netlify CMS からの移行

手順：

1. Git リポジトリを接続します：

   • Dashboard > Add New Site
   • リポジトリをインポートします

2. ビルドを構成します：

   Build command: <your-build-command>
   Publish directory: public  # or _site, or dist
   

3. OAuth には Cloudflare Workers を使用します（Netlify Functions より推奨）

4. デプロイします：

   • main ブランチにプッシュします
   • Netlify が自動的にビルドします

---

GitHub Pages

最適な用途：Jekyll サイト、シンプルな静的サイト

手順：

1. Jekyll を構成します（使用する場合）：

   # _config.yml
   include:
     - admin
   

2. GitHub Actions のワークフローを作成します：

   # .github/workflows/deploy.yml
   name: Deploy
   on:
     push:
       branches: [main]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Build
           run: jekyll build  # or your build command
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./_site
   

3. 認証用の OAuth Worker をデプロイします

4. 管理画面にアクセスします：

   https://username.github.io/repo/admin/
   

---

追加リソース

テンプレート

すべてのテンプレートは templates/ にあります。

• hugo/ - Hugo ブログの完全なセットアップ
• jekyll/ - Jekyll サイトの構成
• 11ty/ - Eleventy ブログのセットアップ
• astro/ - Astro コンテンツコレクション
• cloudflare-workers/ - OAuth プロキシの実装
• vercel-serverless/ - Vercel 認証関数
• collections/ - すぐに使えるコレクションパターン
  • blog-posts.yml
  • docs-pages.yml
  • landing-pages.yml
• admin/ - 管理ページの基本テンプレート

リファレンス

包括的なガイドは references/ にあります。

• common-errors.md - エラーの詳細なトラブルシューティング
• migration-from-decap.md - 完全な移行ガイド
• cloudflare-auth-setup.md - OAuth のステップごとのセットアップ
• config-reference.md - config.yml の完全なドキュメント
• i18n-patterns.md - 国際化の方法
• framework-guides.md - フレームワークごとの詳細

スクリプト

自動化ツールは scripts/ にあります。

• init-sveltia.sh - 新規プロジェクトのセットアップを自動化
• deploy-cf-auth.sh - Cloudflare Workers OAuth をデプロイ
• check-versions.sh - 互換性を確認

公式ドキュメント

• ウェブサイト：https://sveltia.com（近日公開）
• GitHub：https://github.com/sveltia/sveltia-cms
• OAuth Worker：https://github.com/sveltia/sveltia-cms-auth
• npm パッケージ：https://www.npmjs.com/package/@sveltia/cms
• ディスカッション：https://github.com/sveltia/sveltia-cms/discussions

---

トークン効率

推定削減量：60～65%（約9,000トークン削減）

スキルなしの場合（約14,000トークン）：

• 初期調査と内容の把握：2,500トークン
• フレームワークのセットアップにおける試行錯誤：2,000トークン
• OAuth 構成の試行：2,500トークン
• エラーのトラブルシューティング：3,500トークン
• i18n のセットアップ：1,500トークン
• デプロイ構成：2,000トークン

スキルありの場合（約5,000トークン）：

• スキルの検出：100トークン
• スキルの読み込み（SKILL.md）：3,500トークン
• テンプレートの選択：400トークン
• プロジェクト固有の軽微な調整：1,000トークン

---

防止するエラー

このスキルは、よくある8つのエラーを防止します（防止率100％）。

1. ✅ OAuth 認証の失敗
2. ✅ TOML フロントマター生成時のバグ
3. ✅ YAML の解析エラー（厳格な検証）
4. ✅ CMS にコンテンツが一覧表示されない
5. ✅ 「SVELTIA is not defined」エラー
6. ✅ /admin ページの404エラー
7. ✅ 画像のアップロード失敗（HEIC形式）
8. ✅ CORS / COOP ポリシーエラー

---

クイックスタートの例

例1：Cloudflare OAuth を使用した Hugo ブログ

# 1. Create Hugo site
hugo new site my-blog
cd my-blog

# 2. Create admin directory
mkdir -p static/admin

# 3. Copy templates
cp [path-to-skill]/templates/hugo/index.html static/admin/
cp [path-to-skill]/templates/hugo/config.yml static/admin/

# 4. Deploy OAuth Worker
git clone https://github.com/sveltia/sveltia-cms-auth
cd sveltia-cms-auth
npx wrangler deploy

# 5. Configure and test
hugo server
open http://localhost:1313/admin/

---

例2：GitHub Pages 上の Jekyll

# 1. Create Jekyll site
jekyll new my-site
cd my-site

# 2. Create admin
mkdir admin
cp [path-to-skill]/templates/jekyll/index.html admin/
cp [path-to-skill]/templates/jekyll/config.yml admin/

# 3. Add to _config.yml
echo "include:\n  - admin" >> _config.yml

# 4. Deploy
git add .
git commit -m "Add Sveltia CMS"
git push

---

例3：Decap CMS からの移行

# 1. Update script tag in admin/index.html
sed -i 's|decap-cms|@sveltia/cms|g' static/admin/index.html
sed -i 's|decap-cms.js|sveltia-cms.js" type="module|g' static/admin/index.html

# 2. Test locally
hugo server
open http://localhost:1313/admin/

# 3. Deploy
git add static/admin/index.html
git commit -m "Migrate to Sveltia CMS"
git push

---

本番環境での導入例

• Hugo ドキュメント：0deepresearch.com（Hugo + GitHub Pages + Sveltia）
• Jekyll ブログ：keefeere.me（Jekyll + Sveltia + DeepL i18n）
• 11ty ポートフォリオ：さまざまなコミュニティプロジェクト

---

サポート

問題がありますか？ まず references/common-errors.md を確認してください。

解決しませんか？

• GitHub の Issue：https://github.com/sveltia/sveltia-cms/issues
• ディスカッション：https://github.com/sveltia/sveltia-cms/discussions
• Stack Overflow：sveltia-cms タグを付けてください

---

最終更新日：2025-10-24 スキルバージョン：1.0.0 Sveltia CMS バージョン：0.113.3（ベータ版） ステータス：本番環境で使用可能、v1.0 GA は2026年初頭を予定