Communitygithub.com

Sveltia CMS Skill

Richte Sveltia CMS ein – das leichte, Git-gestützte Content Management System als Nachfolger von Decap/Netlify CMS mit 5x kleinerem Bundle (300 KB), GraphQL-Performance und über 260 behobenen Problemen des Vorgängers. Framework-agnostisch für Hugo, Jekyll, 11ty, Gatsby, Astro.

Was ist Sveltia CMS Skill?

Dieses Skill integriert Sveltia CMS, einen modernen, Git-basierten Headless-CMS-Nachfolger von Decap/Netlify CMS, in statische Website-Projekte. Es richtet das Admin-Interface, die Authentifizierung und die Inhaltskonfiguration für Frameworks wie Hugo, Jekyll, 11ty, Astro, Gatsby und Next.js ein. Sveltia CMS bietet ein extrem leichtes Bundle (<500 KB), GraphQL-APIs für schnelles Abrufen von Inhalten, integrierte Bildoptimierung, Mehrsprachigkeit und ein Dark-Mode-Admin-Panel. Das Skill behandelt die Einrichtung des Admin-Verzeichnisses, die Konfigurationsdatei (config.yml), die OAuth-Authentifizierung (z.B. über Cloudflare Workers oder Vercel Serverless Functions) sowie die Migration von Decap/Netlify CMS durch minimalen Code-Austausch.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/sveltia-cms

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Sveltia CMS Skill?

Vollständiges Skill zur Integration von Sveltia CMS in statische Website-Projekte.


Was ist Sveltia CMS?

Sveltia CMS ist ein leichtes, Git-basiertes Headless-Content-Management-System, das von Grund auf als moderner Nachfolger von Decap CMS (ehemals Netlify CMS) entwickelt wurde. Es bietet eine schnelle, intuitive Bearbeitungsoberfläche für Inhalte, die in Git-Repositories gespeichert sind.

Hauptmerkmale

  1. Leicht & Schnell

    • Bundle-Größe: <500 KB (minifiziert/brotliert) vs. 1,5–2,6 MB bei Mitbewerbern
    • Erstellt mit dem Svelte-Compiler (kein Virtual-DOM-Overhead)
    • Verwendet GraphQL-APIs für sofortiges Abrufen von Inhalten
    • Relevanzbasierte Suche über alle Inhalte
  2. Moderne Benutzererfahrung

    • Intuitive Admin-Oberfläche mit voller Viewport-Nutzung
    • Dark-Mode-Unterstützung (folgt Systemeinstellungen)
    • Für Mobilgeräte und Tablets optimiert
    • Drag-and-Drop-Datei-Uploads mit Unterstützung für mehrere Dateien
    • Echtzeit-Vorschau mit sofortigen Aktualisierungen
  3. Git-Native Architektur

    • Inhalte gespeichert als Markdown, MDX, YAML, TOML oder JSON
    • Vollständige Versionskontrolle und Änderungshistorie
    • Keine Herstellerbindung – Inhalte leben mit dem Code
    • Unterstützt GitHub, GitLab, Gitea, Forgejo-Backends
  4. Framework-Agnostisch

    • Wird als Vanilla-JavaScript-Bundle ausgeliefert
    • Funktioniert mit Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit
    • Keine Laufzeitabhängigkeiten von React, Vue oder Frameworks
    • Kompatibel mit jedem Static-Site-Generator
  5. Internationalisierung erster Klasse

    • Mehrsprachigkeit standardmäßig eingebaut
    • DeepL-Übersetzungsintegration per Klick
    • Sprachwechsel während der Bearbeitung
    • Flexible i18n-Strukturen (Dateien, Ordner, Einzeldatei)
  6. Integrierte Bildoptimierung

    • Automatische WebP-Konvertierung
    • Clientseitige Größenanpassung und Optimierung
    • Unterstützung für SVG-Optimierung
    • Konfigurierbare Qualität und Abmessungen

Aktuelle Versionen

  • @sveltia/cms: 0.113.5 (Oktober 2025)
  • Status: Öffentliche Beta (v1.0 voraussichtlich Anfang 2026)
  • Reife: Produktionsreif (265+ behobene Probleme des Vorgängers)

Wann dieses Skill verwenden

✅ Sveltia CMS verwenden, wenn:

  1. Statische Websites erstellt werden

    • Hugo-Blogs und Dokumentationen
    • Jekyll-Seiten und GitHub Pages
    • 11ty (Eleventy)-Projekte
    • Gatsby-Marketingseiten
    • Astro-inhaltsreiche Seiten
  2. Nicht-technische Redakteure Zugriff benötigen

    • Marketing-Teams, die Seiten verwalten
    • Autoren, die Blogbeiträge schreiben
    • Content-Teams ohne Git-Kenntnisse
    • Kunden, die einfache Inhaltsaktualisierungen benötigen
  3. Ein Git-basierter Workflow gewünscht ist

    • Inhaltsversionierung durch Git
    • Inhaltsüberprüfung durch Pull Requests
    • Inhalte leben mit dem Code im Repository
    • CI/CD-Integration für Bereitstellungen
  4. Eine leichte Lösung erforderlich ist

    • Leistungsempfindliche Projekte
    • Mobile-First-Bearbeitung erforderlich
    • Kurze Ladezeiten entscheidend
    • Minimale Bundle-Größe wichtig
  5. Von Decap/Netlify CMS migriert wird

    • Vorhandene config.yml kann wiederverwendet werden
    • Drop-in-Ersatz (1 Zeile ändern)
    • Bessere Leistung und Benutzererfahrung
    • Aktive Wartung und Fehlerbehebungen

❌ Sveltia CMS nicht verwenden, wenn:

  1. Echtzeit-Zusammenarbeit benötigt wird

    • Mehrere Benutzer bearbeiten gleichzeitig (Google-Docs-Stil)
    • Stattdessen Sanity, Contentful oder TinaCMS verwenden
  2. Visuelle Seitenerstellung erforderlich ist

    • Drag-and-Drop-Seitenersteller benötigt
    • Stattdessen Webflow, Builder.io oder TinaCMS (React) verwenden
  3. Hochdynamische Daten

    • E-Commerce mit Echtzeit-Inventar
    • Echtzeit-Dashboards oder Analysen
    • Stattdessen traditionelle Datenbanken (D1, PostgreSQL) verwenden
  4. React-spezifische visuelle Bearbeitung benötigt wird

    • Kontextbezogene Komponentenbearbeitung
    • Stattdessen TinaCMS verwenden (React-fokussiert)

Sveltia CMS vs. TinaCMS

Sveltia verwenden für:

  • Hugo, Jekyll, 11ty, Gatsby (Nicht-React-SSGs)
  • Traditionelle CMS-Admin-Panel-Benutzererfahrung
  • Leichte Bundle-Anforderungen
  • Framework-agnostische Projekte

TinaCMS verwenden für:

  • React, Next.js, Astro (React-Komponenten)
  • Visuelle kontextbezogene Bearbeitung
  • Schema-gesteuerte typsichere Inhalte
  • Moderne Entwicklererfahrung mit TypeScript

Beide sind gültig – Sveltia ergänzt TinaCMS für verschiedene Anwendungsfälle.


Einrichtungsmuster nach Framework

Verwenden Sie das passende Einrichtungsmuster basierend auf Ihrer Framework-Wahl.

1. Hugo-Einrichtung (Am häufigsten)

Hugo ist der beliebteste Static-Site-Generator für Sveltia CMS.

Schritte:

  1. Admin-Verzeichnis erstellen:

    mkdir -p static/admin
    
  2. Admin-Indexseite erstellen:

    <!-- static/admin/index.html -->
    <!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. Konfigurationsdatei erstellen:

    # 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-Entwicklungsserver starten:

    hugo server
    
  5. Admin aufrufen:

    http://localhost:1313/admin/
    

Vorlage: Siehe templates/hugo/


2. Jekyll-Einrichtung

Jekyll wird häufig mit GitHub Pages und Sveltia CMS verwendet.

Schritte:

  1. Admin-Verzeichnis erstellen:

    mkdir -p admin
    
  2. Admin-Indexseite erstellen:

    <!-- admin/index.html -->
    <!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. Konfigurationsdatei erstellen:

    # 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-Entwicklungsserver starten:

    bundle exec jekyll serve
    
  5. Admin aufrufen:

    http://localhost:4000/admin/
    

Vorlage: Siehe templates/jekyll/


3. 11ty (Eleventy)-Einrichtung

11ty funktioniert gut mit Sveltia CMS für flexible statische Seiten.

Schritte:

  1. Admin-Verzeichnis erstellen:

    mkdir -p admin
    
  2. Admin-Indexseite erstellen:

    <!-- admin/index.html -->
    <!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. Konfigurationsdatei erstellen:

    # 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. Passthrough-Copy zu .eleventy.js hinzufügen:

    module.exports = function(eleventyConfig) {
      eleventyConfig.addPassthroughCopy('admin');
      // ... rest of config
    };
    
  5. 11ty-Entwicklungsserver starten:

    npx @11ty/eleventy --serve
    
  6. Admin aufrufen:

    http://localhost:8080/admin/
    

Vorlage: Siehe templates/11ty/


4. Astro-Einrichtung

Astro ist ein modernes Framework, das gut mit Sveltia CMS funktioniert.

Schritte:

  1. Admin-Verzeichnis erstellen:

    mkdir -p public/admin
    
  2. Admin-Indexseite erstellen:

    <!-- public/admin/index.html -->
    <!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. Konfigurationsdatei erstellen:

    # 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-Entwicklungsserver starten:

    npm run dev
    
  5. Admin aufrufen:

    http://localhost:4321/admin/
    

Vorlage: Siehe templates/astro/


5. Framework-agnostische Einrichtung

Gilt für: Gatsby, Next.js (SSG-Modus), SvelteKit, Remix oder jedes Framework

Schritte:

  1. Öffentliches Verzeichnis ermitteln:

    • Gatsby: static/
    • Next.js: public/
    • SvelteKit: static/
    • Remix: public/
  2. Admin-Verzeichnis im öffentlichen Ordner erstellen:

    mkdir -p <public-folder>/admin
    
  3. Admin-Indexseite erstellen:

    <!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. Konfigurationsdatei erstellt, die auf Ihre Inhaltsstruktur zugeschnitten ist:

    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: <your-media-path>
    public_folder: <your-public-path>
    
    collections:
      # Basierend auf Ihrer Inhaltsstruktur definieren
    
  5. Admin aufrufen:

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

Authentifizierungseinrichtung

Wählen Sie die Authentifizierungsmethode, die zu Ihrer Bereitstellungsplattform passt.

Option 1: Cloudflare Workers OAuth (Empfohlen) 🔥

Am besten für: Cloudflare Pages, Cloudflare Workers, beliebige Bereitstellung

Dies verwendet den offiziellen sveltia-cms-auth Cloudflare Worker für OAuth.

Schritte:

  1. Worker bereitstellen:

    # Auth-Worker klonen
    git clone https://github.com/sveltia/sveltia-cms-auth
    cd sveltia-cms-auth
    
    # Abhängigkeiten installieren
    npm install
    
    # Für Cloudflare Workers bereitstellen
    npx wrangler deploy
    

    Oder Ein-Klick-Bereitstellung verwenden:

  2. OAuth-App auf GitHub registrieren:

  3. Worker-Umgebungsvariablen konfigurieren:

    # GitHub-Anmeldedaten setzen
    npx wrangler secret put GITHUB_CLIENT_ID
    # Ihre Client ID einfügen
    
    npx wrangler secret put GITHUB_CLIENT_SECRET
    # Ihr Client Secret einfügen
    
    # Optional: Auf bestimmte Domains beschränken
    npx wrangler secret put ALLOWED_DOMAINS
    # Beispiel: yourdomain.com,*.yourdomain.com
    
  4. CMS-Konfiguration aktualisieren:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://your-worker.workers.dev  # ← Diese Zeile hinzufügen
    
  5. Authentifizierung testen:

    • Öffnen Sie /admin/ Ihrer Seite
    • Klicken Sie auf "Login with GitHub"
    • Autorieren Sie die App
    • Sie sollten zurück zum CMS weitergeleitet werden

Vollständige Anleitung: Siehe references/cloudflare-auth-setup.md

Vorlage: Siehe templates/cloudflare-workers/


Option 2: Vercel Serverless Functions

Am besten für: Vercel-Bereitstellungen

Schritte:

  1. API-Route erstellen:

    // api/auth.ts
    export default async function handler(req, res) {
      // OAuth-Behandlungslogik
      // Siehe templates/vercel-serverless/api-auth.ts
    }
    
  2. Umgebungsvariablen in Vercel setzen:

    GITHUB_CLIENT_ID=your_client_id
    GITHUB_CLIENT_SECRET=your_client_secret
    
  3. CMS-Konfiguration aktualisieren:

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

Vorlage: Siehe templates/vercel-serverless/


Fehlerbehebung bei häufigen Problemen

Problem: Admin-Seite wird nicht geladen

Ursachen und Lösungen:

  1. Überprüfen Sie das Admin-Verzeichnis:

    • Bestätigen Sie, dass index.html und config.yml vorhanden sind
    • Überprüfen Sie die Verzeichnisstruktur (z.B. static/admin/ für Hugo, admin/ für Jekyll)
  2. CSS-Browser-Cache löschen:

    # Hard-Refresh versuchen
    # Chrome/Firefox: Strg+Umschalt+R
    # Mac: Cmd+Umschalt+R
    

    Oder DevTools > Application > Cache > Clear site data

  3. Konfigurations-YAML validieren:

    # Online-YAML-Validator verwenden
    # https://www.yamllint.com/
    

Problem: Authentifizierungsfehler

Ursachen und Lösungen:

  1. Überprüfen Sie die OAuth-App-Einstellungen:

    • Bestätigen Sie, dass Client ID und Client Secret korrekt sind
    • Überprüfen Sie, ob die Authorization callback URL mit der Worker-URL übereinstimmt
  2. Überprüfen Sie die CORS-Politik:

    • Stellen Sie sicher, dass der OAuth-Worker Anfragen von Ihrer Domain zulässt
    • Cloudflare-Worker erfordern explizite CORS-Header
  3. Überprüfen Sie die Umgebungsvariablen:

    # Prüfen, ob Variablen richtig gesetzt sind
    npx wrangler secret list
    

Problem: Inhalte werden nicht aufgelistet

Ursachen und Lösungen:

  1. Überprüfen Sie config.yml-Pfade:

    • media_folder, public_folder und Sammlungs-folder-Pfade validieren
    • Stellen Sie sicher, dass sie für die Struktur Ihres Projekts korrekt sind
  2. Überprüfen Sie die Berechtigungen:

    • Bestätigen Sie, dass die GitHub-OAuth-App Lesezugriff auf Ihr Repository hat
  3. Überprüfen Sie das Branch-Ziel:

    • Stellen Sie sicher, dass branch: main mit Ihrem Standard-Branch übereinstimmt

Problem: YAML-Parse-Fehler

Ursachen und Lösungen:

  1. Einrückung überprüfen:

    • YAML ist einrückungsempfindlich – konsistente Leerzeichen verwenden (keine Tabs)
  2. Sonderzeichen escapen:

    • Verwenden Sie Anführungszeichen für Zeichenfolgen mit Sonderzeichen (:, #, {, })
  3. Kommentare entfernen:

    • Entfernen Sie alle YAML-Kommentare (#) temporär, um sie als Fehlerursache auszuschließen

Migrationsleitfaden

Migration von Decap/Netlify CMS zu Sveltia CMS

Sveltia CMS ist ein Drop-in-Ersatz für Decap CMS. Die minimale Änderung besteht darin, die Skript-URL zu ersetzen.

Schritte:

  1. Skript-URL ersetzen:

    - <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" type="module"></script>
    
  2. Gleiche config.yml wiederverwenden – Sveltia CMS ist vollständig abwärtskompatibel mit der Decap-CMS-Konfiguration. Keine Änderungen an Ihren Sammlungen, Feldern oder Workflows erforderlich.

  3. Neue Funktionen genießen:

    • Schnellere Admin-Panel-Ladezeiten
    • Bessere mobile Bearbeitung
    • Dark-Mode-Unterstützung
    • GraphQL-betriebenes Abrufen
    • Fortlaufende Fehlerbehebungen und Aktualisierungen

Referenzen & Vorlagen


Verwandte Skills

  • reference/hugo-blog-template – Hugo-Blog-Setup
  • reference/jekyll-github-pages – Jekyll-GitHub-Pages-Einrichtung
  • reference/astro-content-collections – Astro-Inhaltssammlungen
  • reference/11ty-image-optimization – 11ty-Bildoptimierung

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Verwandte Skills