sveltia-cms

Name: sveltia-cms
Author: jackspace

github.com/jackspace開発1649 回インストール12 週間前に更新

リポジトリ

sveltia-cms について

静的サイトに Sveltia CMS を導入するためのスキルで、セットアップ、設定、認証方法を案内します。Git ベースのコンテンツ編集を導入する、Hugo、Jekyll、11ty、Astro などのサイト開発者向けです。

主な機能

01フレームワーク別セットアップガイド
02Git バックエンド設定
03OAuth 認証ガイド
04コンテンツコレクションのテンプレート
05多言語設定
06ローカルリポジトリのワークフロー

活用シーン

01静的サイトに編集画面を追加
02CMS から Git リポジトリへのアクセス設定
03CMS 導入時の OAuth を計画
04多言語コンテンツ編集を設定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jackspace/claudeskillz --skill sveltia-cms

インストール後、Claude Code で/sveltia-cmsを入力して読み込まれたか確認します。

同梱ファイルREADME.mdSKILL.json

詳細

Sveltia CMS スキル

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

Sveltia CMS とは？

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

主な機能

軽量で高速
- バンドルサイズ：<500 KB（圧縮・brotlied）で、競合製品の 1.5-2.6 MB より小さい
- Svelte コンパイラーを使用して構築（仮想 DOM によるオーバーヘッドなし）
- GraphQL API を使用してコンテンツを即座に取得
- すべてのコンテンツを対象に関連度ベースで検索
モダンなユーザー体験
- ビューポート全体を活用する直感的な管理インターフェース
- ダークモード対応（システム設定に従います）
- モバイルとタブレットに最適化
- 複数ファイルに対応したドラッグ＆ドロップでのファイルアップロード
- 即時更新されるリアルタイムプレビュー
Git ネイティブなアーキテクチャ
- コンテンツを Markdown、MDX、YAML、TOML、または JSON として保存
- 完全なバージョン管理と変更履歴
- ベンダーロックインなし — コンテンツはコードとともに保存
- GitHub、GitLab、Gitea、Forgejo のバックエンドに対応
フレームワークに依存しない
- バニラ JavaScript バンドルとして配信
- Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit で動作
- React、Vue、フレームワークのランタイム依存なし
- あらゆる静的サイトジェネレーターと互換性あり
多言語化を標準搭載
- 複数言語への対応を標準搭載
- ワンクリックで DeepL 翻訳を連携
- 編集中にロケールを切り替え
- 柔軟な i18n 構造（ファイル、フォルダー、単一ファイル）
画像最適化機能を標準搭載
- WebP への自動変換
- クライアント側でのサイズ変更と最適化
- SVG 最適化に対応
- 品質とサイズを設定可能

現在のバージョン

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

このスキルを使う場合

✅ Sveltia CMS を使う場面：

静的サイトを構築する
- Hugo のブログやドキュメント
- Jekyll サイトや GitHub Pages
- 11ty（Eleventy）プロジェクト
- Gatsby のマーケティングサイト
- コンテンツの多い Astro サイト
技術に詳しくない編集者がアクセスする必要がある
- ページを管理するマーケティングチーム
- ブログ記事を執筆する著者
- Git の知識がないコンテンツチーム
- コンテンツを簡単に更新したいクライアント
Git ベースのワークフローが望ましい
- Git によるコンテンツのバージョン管理
- プルリクエストによるコンテンツレビュー
- リポジトリ内でコンテンツをコードとともに管理
- デプロイのための CI/CD 連携
軽量なソリューションが必要
- パフォーマンスが重視されるプロジェクト
- モバイルファーストの編集が必要
- 高速な読み込みが重要
- 最小限のバンドルサイズが重要
Decap/Netlify CMS から移行する
- 既存の config.yml を再利用可能
- そのまま置き換え可能（1 行を変更）
- パフォーマンスと UX が向上
- 積極的なメンテナンスとバグ修正

❌ Sveltia CMS を使わない場面：

リアルタイムの共同編集が必要
- 複数ユーザーが同時に編集する（Google Docs のような形式）
- 代わりに Sanity、Contentful、または TinaCMS を使用
ビジュアルなページ作成が必要
- ドラッグ＆ドロップ式のページビルダーが必要
- 代わりに Webflow、Builder.io、または TinaCMS（React）を使用
高度に動的なデータを扱う
- リアルタイムの在庫管理を伴う E コマース
- リアルタイムのダッシュボードや分析
- 代わりに従来型のデータベース（D1、PostgreSQL）を使用
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 で最もよく使われている静的サイトジェネレーターです。

手順：

管理ディレクトリを作成します：
```
mkdir -p static/admin
```

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


<!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>

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

# 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' }

Hugo の開発サーバーを起動します：
```
hugo server
```
管理画面にアクセスします：
```
http://localhost:1313/admin/
```

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

2. Jekyll のセットアップ

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

手順：

管理ディレクトリを作成します：
```
mkdir -p admin
```

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


<!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>

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

# 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' }

Jekyll の開発サーバーを起動します：
```
bundle exec jekyll serve
```
管理画面にアクセスします：
```
http://localhost:4000/admin/
```

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

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

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

手順：

管理ディレクトリを作成します：
```
mkdir -p admin
```

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


<!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>

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

# 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' }

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

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

11ty の開発サーバーを起動します：
```
npx @11ty/eleventy --serve
```
管理画面にアクセスします：
```
http://localhost:8080/admin/
```

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

4. Astro のセットアップ

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

手順：

管理ディレクトリを作成します：
```
mkdir -p public/admin
```

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


<!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>

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

# 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' }

Astro の開発サーバーを起動します：
```
npm run dev
```
管理画面にアクセスします：
```
http://localhost:4321/admin/
```

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

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

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

手順：

公開ディレクトリを確認します：
- Gatsby：static/
- Next.js：public/
- SvelteKit：static/
- Remix：public/
公開フォルダー内に管理ディレクトリを作成します：
```
mkdir -p <public-folder>/admin
```

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

<!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>

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

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

管理画面にアクセスします：
```
http://localhost:<port>/admin/
```

認証のセットアップ

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

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

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

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

手順：

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

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

CMS の設定を更新します：

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

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

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

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

オプション 2：Vercel Serverless Functions

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

手順：

API ルートを作成します：

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

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

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

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）

セットアップ：

個人用アクセストークンを生成します。
- GitHub：https://github.com/settings/tokens
- スコープ：repo（プライベートリポジトリへの完全なアクセス権）

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

# admin/config.yml
backend:
  name: github
  repo: owner/repo
  branch: main

local_backend: true  # Enable local mode

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 を使って組み込まれています。

セットアップ：

DeepL API キーを取得します。
- https://www.deepl.com/pro-api で登録します
- 無料プラン：月 500,000 文字

設定に追加します。

# 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

エディターで使用します。
- デフォルト以外のロケールに切り替えます
- 「[デフォルトロケール]から翻訳」ボタンをクリックします
- 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 を使用する必要がある場合:

CMS の保存後に区切り文字を手動で修正します
TOML を検証する pre-commit フックを使用します
ベータ版の修正を待ちます（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 プロキシを使用してください。

テストチェックリスト

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

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

デプロイパターン

Cloudflare Pages

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

手順：

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

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

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

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

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

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

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

Vercel

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

手順：

Git リポジトリを接続します：
- Dashboard > Add New Project
- リポジトリをインポートします

ビルドを構成します：

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

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

環境変数を設定します：

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

デプロイします：
- main ブランチにプッシュします
- Vercel が自動的にビルドします

Netlify

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

手順：

Git リポジトリを接続します：
- Dashboard > Add New Site
- リポジトリをインポートします

ビルドを構成します：

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

OAuth には Cloudflare Workers を使用します（Netlify Functions より推奨）
デプロイします：
- main ブランチにプッシュします
- Netlify が自動的にビルドします

GitHub Pages

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

手順：

Jekyll を構成します（使用する場合）：
```
# _config.yml
include:
  - admin
```

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

認証用の OAuth Worker をデプロイします
管理画面にアクセスします：
```
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％）。

✅ OAuth 認証の失敗
✅ TOML フロントマター生成時のバグ
✅ YAML の解析エラー（厳格な検証）
✅ CMS にコンテンツが一覧表示されない
✅ 「SVELTIA is not defined」エラー
✅ /admin ページの404エラー
✅ 画像のアップロード失敗（HEIC形式）
✅ 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年初頭を予定

Markdown 対応

ログインしてコメント

基本情報

作者: jackspace
リポジトリ: jackspace/claudeskillz
カテゴリ: 開発
インストール数: 49
GitHub スター: 16

問題を報告