Sveltia CMS Skill

Complete skill for integrating Sveltia CMS into static site projects.

---

Current Versions

• @sveltia/cms: 0.128.5 (verified January 2026)
• Status: Public Beta (v1.0 expected early 2026)
• Maturity: Production-ready (270+ issues solved from predecessor)

---

When to Use This Skill

✅ Use Sveltia CMS When:

• Git-based workflow desired (content as Markdown/YAML/TOML/JSON in repository)
• Lightweight solution required (<500 KB vs 1.5-2.6 MB for competitors)
• Migrating from Decap/Netlify CMS (drop-in replacement, change 1 line)
• Non-technical editors need access without Git knowledge

❌ Don't Use Sveltia CMS When:

• Real-time collaboration needed (multiple users editing simultaneously) - Use Sanity, Contentful, or TinaCMS instead
• Visual page building required (drag-and-drop) - Use Webflow, Builder.io instead
• React-specific visual editing needed - Use TinaCMS instead

---

Breaking Changes & Updates (v0.105.0+)

v0.127.0 (December 29, 2025) - slug_length Deprecation

DEPRECATION: The slug_length collection option is deprecated and will be removed in v1.0.

Migration:

# ❌ Deprecated (pre-v0.127.0)
collections:
  - name: posts
    slug_length: 50

# ✅ New (v0.127.0+)
slug:
  maxlength: 50

Timeline: Will be removed in Sveltia CMS 1.0 (expected early 2026).

Source: Release v0.127.0

---

v0.120.0 (November 24, 2025) - Author Template Tags

New Feature: Hidden widget now supports author template tags:

• {{author-email}} - Signed-in user's email
• {{author-login}} - Signed-in user's login name
• {{author-name}} - Signed-in user's display name

Usage:

fields:
  - label: Author Email
    name: author_email
    widget: hidden
    default: '{{author-email}}'

Commit message templates also support {{author-email}} tag.

---

v0.119.0 (November 16, 2025) - TOML Config Support

New Feature: Configuration files can now be written in TOML format (previously YAML-only).

Migration:

# admin/config.toml (NEW)
[backend]
name = "github"
repo = "owner/repo"
branch = "main"

media_folder = "static/images/uploads"
public_folder = "/images/uploads"

Recommendation: YAML is still preferred for better tooling support.

---

v0.118.0 (November 15, 2025) - TypeScript Breaking Change

BREAKING: Renamed SiteConfig export to CmsConfig for compatibility with Netlify/Decap CMS.

Migration:

// ❌ Old (v0.117.x)
import type { SiteConfig } from '@sveltia/cms';

// ✅ New (v0.118.0+)
import type { CmsConfig } from '@sveltia/cms';

const config: CmsConfig = {
  backend: { name: 'github', repo: 'owner/repo' },
  collections: [/* ... */],
};

Impact: TypeScript users only. Breaking change for type imports.

---

v0.117.0 (November 14, 2025) - Enhanced Validation

New Features:

• Exported CmsConfig type for direct TypeScript import
• Enhanced config validation for collection names, field types, and relation references
• Better error messages for invalid configurations

---

v0.115.0 (November 5, 2025) - Field-Specific Media Folders

New Feature: Override media_folder at the field level (not just collection level).

Usage:

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    media_folder: static/images/posts  # Collection-level default
    fields:
      - label: Featured Image
        name: image
        widget: image
        media_folder: static/images/featured  # ← Field-level override
        public_folder: /images/featured

      - label: Author Avatar
        name: avatar
        widget: image
        media_folder: static/images/avatars  # ← Another override
        public_folder: /images/avatars

Use case: Different media folders for different image types in same collection.

---

v0.113.5 (October 27, 2025) - Logo Deprecation

DEPRECATION: logo_url option is now deprecated. Migrate to logo.src.

Migration:

# ❌ Deprecated
logo_url: https://yourdomain.com/logo.svg

# ✅ New (v0.113.5+)
logo:
  src: https://yourdomain.com/logo.svg

---

v0.105.0 (September 15, 2024) - Security Breaking Change

BREAKING: sanitize_preview default changed to true for Markdown widget (XSS prevention).

Impact:

• Before v0.105.0: sanitize_preview: false (compatibility with Netlify/Decap CMS, but vulnerable to XSS)
• After v0.105.0: sanitize_preview: true (secure by default)

Migration:

collections:
  - name: posts
    fields:
      - label: Body
        name: body
        widget: markdown
        sanitize_preview: false  # ← Add ONLY if you trust all CMS users

Recommendation: Keep default (true) unless disabling fixes broken preview AND you fully trust all CMS users.

---

Configuration Options

Global Slug Options (v0.128.0+)

Configure slug generation behavior globally:

slug:
  encoding: unicode-normalized
  clean_accents: false
  sanitize_replacement: '-'
  lowercase: true   # Default: convert to lowercase (v0.128.0+)
  maxlength: 50     # Default: unlimited (v0.127.0+)

lowercase (v0.128.0+): Set to false to preserve original casing in slugs (e.g., "MyBlogPost" instead of "myblogpost").

Use case: Mixed-case URLs or file names where case matters.

Source: Release v0.128.0, GitHub Issue #594

---

Raw Format for Text Files (v0.126.0+)

New raw format allows editing files without front matter (CSV, JSON, YAML, plain text). Must have single body field with widget type: code, markdown, richtext, or text.

Use Cases:

• Edit configuration files (JSON, YAML)
• Manage CSV data
• Edit plain text files

Configuration:

collections:
  - name: config
    label: Configuration Files
    files:
      - label: Site Config
        name: site_config
        file: config.json
        format: raw  # ← NEW format type
        fields:
          - label: Config
            name: body
            widget: code
            default_language: json

Restrictions:

• Only one field allowed (must be named body)
• Widget must be: code, markdown, richtext, or text
• No front matter parsing

Source: Release v0.126.0

---

Number Field String Encoding (v0.125.0+)

New value_type option for Number field accepts int/string and float/string to save numbers as strings instead of numbers in front matter.

Use Case: Some static site generators or schemas require numeric values stored as strings (e.g., age: "25" instead of age: 25).

Configuration:

fields:
  - label: Age
    name: age
    widget: number
    value_type: int/string  # Saves as "25" not 25

  - label: Price
    name: price
    widget: number
    value_type: float/string  # Saves as "19.99" not 19.99

Source: Release v0.125.0, GitHub Issue #574

---

Editor Pane Locale via URL Query (v0.126.0+)

Override editor locale via URL query parameter ?_locale=fr to get edit links for specific locales.

Use Case: Generate direct edit links for translators or content editors for specific languages.

Example:

https://yourdomain.com/admin/#/collections/posts/entries/my-post?_locale=fr

Source: Release v0.126.0, GitHub Issue #585

---

Richtext Field Type Alias (v0.124.0+)

Added richtext as an alias for markdown widget to align with Decap CMS terminology. Both work identically.

Configuration:

fields:
  - label: Body
    name: body
    widget: richtext  # ← NEW alias for markdown

Future: HTML output support planned for richtext field type.

Source: Release v0.124.0

---

Setup Pattern (Framework-Agnostic)

All frameworks follow the same pattern:

1. Create admin directory in public/static folder:

   • Hugo: static/admin/
   • Jekyll: admin/
   • 11ty: admin/ (with passthrough copy)
   • Astro: public/admin/
   • Next.js: public/admin/

2. Create admin/index.html:

   <!doctype html>
   <html lang="en"
   how to use sveltia-cms
   CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
   How to use sveltia-cms on Cursor
   AI-first code editor with Composer
   1
   Prerequisites
   Before installing skills in Cursor, ensure your development environment meets these requirements:
   ›Cursor installed and configured on your development machine
   ›Node.js version 16.0+ with npm package manager (verify with node --version)
   ›Active project directory or workspace where you want to add sveltia-cms
   2
   Execute installation command
   Execute the skills CLI command in your project's root directory to begin installation:
   $npx skills add https://github.com/jezweb/claude-skills --skill sveltia-cmscopy
   The skills CLI fetches sveltia-cms from GitHub repository jezweb/claude-skills and configures it for Cursor.
   3
   Select Cursor when prompted
   The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
   ◆ Which agents do you want to install to?
   │
   │ ── Universal (.agents/skills) ── always included ────
   │   • Amp
   │   • Antigravity
   │   • Cline
   │   • Codex
   │ ●Cursor(selected)
   │   • Cursor
   │   • Windsurf
   4
   Verify installation
   Confirm successful installation by checking the skill directory location:
   .cursor/skills/sveltia-cms
   Reload or restart Cursor to activate sveltia-cms. Access the skill through slash commands (e.g., /sveltia-cms) or your agent's skill management interface.
   ⚠
   Security & Verification Notice
   We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
   Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
   Additional Resources
   ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?