sveltia-cms

What this skill does

# Sveltia CMS Skill

Complete skill for integrating Sveltia CMS into static site projects.

---

## What is Sveltia CMS?

**Sveltia CMS** is a Git-based lightweight headless content management system built from scratch as the modern successor to Decap CMS (formerly Netlify CMS). It provides a fast, intuitive editing interface for content stored in Git repositories.

### Key Features

1. **Lightweight & Fast**
   - Bundle size: <500 KB (minified/brotlied) vs 1.5-2.6 MB for competitors
   - Built with Svelte compiler (no virtual DOM overhead)
   - Uses GraphQL APIs for instant content fetching
   - Relevance-based search across all content

2. **Modern User Experience**
   - Intuitive admin interface with full viewport utilization
   - Dark mode support (follows system preferences)
   - Mobile and tablet optimized
   - Drag-and-drop file uploads with multiple file support
   - Real-time preview with instant updates

3. **Git-Native Architecture**
   - Content stored as Markdown, MDX, YAML, TOML, or JSON
   - Full version control and change history
   - No vendor lock-in - content lives with code
   - Supports GitHub, GitLab, Gitea, Forgejo backends

4. **Framework-Agnostic**
   - Served as vanilla JavaScript bundle
   - Works with Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit
   - No React, Vue, or framework runtime dependencies
   - Compatible with any static site generator

5. **First-Class Internationalization**
   - Multiple language support built-in
   - One-click DeepL translation integration
   - Locale switching while editing
   - Flexible i18n structures (files, folders, single file)

6. **Built-In Image Optimization**
   - Automatic WebP conversion
   - Client-side resizing and optimization
   - SVG optimization support
   - Configurable quality and dimensions

### Current Versions

- **@sveltia/cms**: 0.113.5 (October 2025)
- **Status**: Public Beta (v1.0 expected early 2026)
- **Maturity**: Production-ready (265+ issues solved from predecessor)

---

## When to Use This Skill

### ✅ Use Sveltia CMS When:

1. **Building Static Sites**
   - Hugo blogs and documentation
   - Jekyll sites and GitHub Pages
   - 11ty (Eleventy) projects
   - Gatsby marketing sites
   - Astro content-heavy sites

2. **Non-Technical Editors Need Access**
   - Marketing teams managing pages
   - Authors writing blog posts
   - Content teams without Git knowledge
   - Clients needing easy content updates

3. **Git-Based Workflow Desired**
   - Content versioning through Git
   - Content review through pull requests
   - Content lives with code in repository
   - CI/CD integration for deployments

4. **Lightweight Solution Required**
   - Performance-sensitive projects
   - Mobile-first editing needed
   - Quick load times critical
   - Minimal bundle size important

5. **Migrating from Decap/Netlify CMS**
   - Existing config.yml can be reused
   - Drop-in replacement (change 1 line)
   - Better performance and UX
   - Active maintenance and bug fixes

### ❌ Don't Use Sveltia CMS When:

1. **Real-Time Collaboration Needed**
   - Multiple users editing simultaneously (Google Docs-style)
   - Use Sanity, Contentful, or TinaCMS instead

2. **Visual Page Building Required**
   - Drag-and-drop page builders needed
   - Use Webflow, Builder.io, or TinaCMS (React) instead

3. **Highly Dynamic Data**
   - E-commerce with real-time inventory
   - Real-time dashboards or analytics
   - Use traditional databases (D1, PostgreSQL) instead

4. **React-Specific Visual Editing Needed**
   - In-context component editing
   - Use TinaCMS instead (React-focused)

### Sveltia CMS vs TinaCMS

**Use Sveltia** for:
- Hugo, Jekyll, 11ty, Gatsby (non-React SSGs)
- Traditional CMS admin panel UX
- Lightweight bundle requirements
- Framework-agnostic projects

**Use TinaCMS** for:
- React, Next.js, Astro (React components)
- Visual in-context editing
- Schema-driven type-safe content
- Modern developer experience with TypeScript

**Both are valid** - Sveltia complements TinaCMS for different use cases.

---

## Setup Patterns by Framework

Use the appropriate setup pattern based on your framework choice.

### 1. Hugo Setup (Most Common)

Hugo is the most popular static site generator for Sveltia CMS.

**Steps:**

1. **Create admin directory:**
   ```bash
   mkdir -p static/admin
   ```

2. **Create admin index page:**
   ```html
   <!-- 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. **Create config file:**
   ```yaml
   # 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. **Start Hugo dev server:**
   ```bash
   hugo server
   ```

5. **Access admin:**
   ```
   http://localhost:1313/admin/
   ```

**Template**: See `templates/hugo/`

---

### 2. Jekyll Setup

Jekyll is commonly used with GitHub Pages and Sveltia CMS.

**Steps:**

1. **Create admin directory:**
   ```bash
   mkdir -p admin
   ```

2. **Create admin index page:**
   ```html
   <!-- 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. **Create config file:**
   ```yaml
   # 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. **Start Jekyll dev server:**
   ```bash
   bundle exec jekyll serve
   ```

5. **Access admin:**
   ```
   http://localhost:4000/admin/
   ```

**Template**: See `templates/jekyll/`

---

### 3. 11ty (Eleventy) Setup

11ty works well with Sveltia CMS for flexible static sites.

**Steps:**

1. **Create admin directory:**
   ```bash
   mkdir -p admin
   ```

2. **Create admin index page:**
   ```html
   <!-- 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. **Create config file:**
   ```yaml
   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main

   media_folder: src/assets/images
   public_folder: /assets/images