Sveltia CMS

Configuration Basics ​

This guide covers the basics of configuring Sveltia CMS using a configuration file. It explains the supported file formats, how to specify the configuration file location, and how to enable validation and autocomplete in your code editor.

Future Plans

We plan to introduce a graphical configuration editor in a future release, allowing users to create and modify the configuration directly within the CMS interface. For now, please refer to this guide for manual configuration.

Compatibility with Other Platforms ​

Netlify CMS and Decap CMS ​

Sveltia CMS is designed to be compatible with Netlify/Decap CMS configuration files. You can use your existing config.yml file from Netlify/Decap CMS with Sveltia CMS, and it should work without any issues in most cases. However, please note that some options may have been deprecated or replaced in Sveltia CMS, so it’s recommended to review the configuration file and make any necessary adjustments. See the migration guide for details.

Pages CMS ​

Pages CMS was inspired by Netlify CMS and shares a similar configuration structure. The .pages.yml file can’t be used as is, but most of its options have a direct equivalent in Sveltia CMS. See the migration guide for how to convert it. There are also AI tools available to assist with this process.

Supported Formats ​

Sveltia CMS supports configuration files in the following formats:

YAML ​

The CMS configuration file is usually written in YAML format. Ensure that your file adheres to proper YAML syntax to avoid parsing errors. If you are new to YAML, consider reviewing a YAML tutorial to familiarize yourself with the syntax.

Sveltia CMS currently uses the yaml npm package for parsing and serializing YAML files.

Here are some key YAML syntax features to keep in mind:

Comments ​

YAML supports comments using the # symbol. Comments can be placed on their own line or at the end of a line:

yaml
# This is a comment
title: My Site # This is an inline comment

Shorthand Notation ​

Sometimes we use shorthand notation for brevity. For example,

yaml
fields:
  - name: title
    label: Title
    widget: string
  - name: align
    label: Alignment
    widget: select
    options:
      - left
      - center
      - right

is the same as

yaml
fields:
  - { name: title, label: Title, widget: string }
  - { name: align, label: Alignment, widget: select, options: [left, center, right] }

Quoting Strings ​

In YAML, strings can be quoted using single (') or double (") quotes. Quoting is necessary when the string contains special characters, leading/trailing spaces, or when you want to preserve the exact formatting. For example:

yaml
description: 'A site with special characters: #, :, -'

Multiline Strings ​

YAML allows multiline strings using the | (literal) or > (folded) indicators. For example:

yaml
description: |
  This is a multiline
  string that preserves
  line breaks.
summary: >
  This is a folded multiline string that replaces line breaks with spaces.

Anchors and Aliases ​

YAML supports anchors and aliases to reuse configuration snippets. This is an advanced feature that can help reduce duplication. For example:

yaml
fields:
  - &title_field
    name: title
    label: Title
    widget: string
  - name: subtitle
    label: Subtitle
    widget: string
  - <<: *title_field
    name: headline
    label: Headline

TOML ​

TOML format is also supported for configuration files. If you prefer TOML, create a file named config.toml instead of config.yml and write the configuration in TOML syntax. Make sure to add a <link> tag in your HTML to point to the file with the correct MIME type (see the Config URL section below).

Sveltia CMS currently uses the smol-toml npm package for parsing and serializing TOML files.

JSON ​

Sveltia CMS also supports JSON format for configuration files. However, JSON is mainly intended for programmatic generation of configuration files rather than manual editing, due to its verbosity and lack of support for comments.

To use a JSON configuration file, create a file named config.json instead of config.yml and write the configuration in JSON syntax, and add a <link> tag in your HTML to point to the file with the correct MIME type (see the Config URL section below).

We don’t support JSONC, JSON5, or other JSON variants — only standard JSON that can be parsed by JSON.parse and serialized by JSON.stringify. If you want to write comments in your configuration file, use YAML format instead.

JavaScript/TypeScript ​

Instead of using a static configuration file, you can also provide the CMS configuration as a JavaScript object when manually initializing the CMS. It gives you the most flexibility and control over the configuration, allowing you to dynamically generate or modify the configuration based on your application logic.

The field configuration for custom editor components also uses JavaScript objects.

Config URL ​

You can customize the configuration file location and format by specifying a URL in your HTML using a <link> tag with rel="cms-config-url". This is useful if you want to store the configuration file in a different location or use a different format than the default.

Configuration is Public

Regardless of the location, the configuration file is publicly accessible on the web server. Avoid including sensitive information, such as API keys or passwords, in the configuration file.

Custom Configuration File Path ​

By default, Sveltia CMS looks for a YAML configuration file named config.yml located in the same folder as the index.html file. The file is typically accessible at /admin/config.yml on a web server. There is no need to specify this default location explicitly.

To specify a custom configuration file path, add a <link> tag in your HTML’s <head> section:

html
<link href="/cms/config.yaml" type="application/yaml" rel="cms-config-url" />

The MIME type for YAML files is application/yaml (standardized) or text/yaml (legacy). Both are supported.

TOML or JSON Configuration File ​

If you use a TOML or JSON configuration file instead of YAML, you need to add a <link> tag with the appropriate MIME type. This tells Sveltia CMS to load the configuration from the specified file instead of the default config.yml. Below are examples for both formats.

html
<link href="/admin/config.toml" type="application/toml" rel="cms-config-url" />
html
<link href="/admin/config.json" type="application/json" rel="cms-config-url" />

Multiple Configuration Files ​

You can specify multiple configuration files by adding multiple <link> tags. Sveltia CMS will merge them in the order they appear in the HTML.

html
<link href="/admin/config.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/authors.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/pages.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/posts.yml" type="application/yaml" rel="cms-config-url" />

Limitations

YAML anchors, aliases and merge keys only work if they are in the same file. This is because the files are parsed as separate JavaScript objects and then merged using the deepmerge library.

Also, modularized configuration files may raise errors if you enable JSON schema validation in your code editor, as the schema expects a complete configuration object.

Validation and Autocomplete ​

For a better development experience, Sveltia CMS provides JSON schema support and TypeScript types for configuration validation and autocomplete.

JSON Schema ​

Sveltia CMS provides a full JSON schema for the configuration file, so you can get autocomplete and validation in your favorite code editor while editing the CMS configuration. The schema is generated from the source and always up to date with the latest CMS version.

Enabling JSON Schema Validation in VS Code ​

If you use VS Code, you can enable it for the YAML configuration file by installing the YAML extension and adding the following comment to the top of config.yml:

yaml
# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

For TOML files, install the Even Better TOML extension and add the following comment to the top of config.toml:

toml
#:schema https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

JSON files have native support in VS Code, so no extension is needed. Just add the following line to the top of config.json, within the curly braces:

json
"$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json",
Workspace-level configuration

Instead of adding the schema comment to the top of the configuration file, you can also set it up at the workspace level in VS Code. Add the following to your project’s VS Code settings file at .vscode/settings.json, within the outer curly braces.

For YAML files:

jsonc
"yaml.schemas": {
  "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json": ["/public/admin/config.yml"]
}

For JSON files:

jsonc
"json.schemas": [
  {
    "fileMatch": ["/public/admin/config.json"],
    "url": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json"
  }
]

The configuration file location varies by framework and project structure, so adjust the path accordingly. For example, if you use Hugo, the file is typically located in the /static/admin/ directory.

Other Editors ​

Check your code editor or IDE documentation to see if it supports JSON schema validation for YAML, TOML, or JSON files. If supported, use the following schema URL:

https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

WebStorm and other JetBrains IDEs have built-in support for JSON schema validation in YAML and JSON files. You can configure the schema in the IDE settings.

TypeScript Support ​

When using the @sveltia/cms package in a TypeScript-enabled project, you can get type checking and autocomplete for the API, including the configuration object when manually initializing the CMS.

The type definitions are generated from the JSDoc comments in the source code, ensuring they are accurate and up to date with the latest CMS version.

Runtime Validation ​

Sveltia CMS validates the configuration every time it loads. Anything that would break the CMS is listed on the login screen, and users can’t sign in until it’s fixed, so a broken configuration never reaches the content editor. Everything the CMS can safely work around is logged to the browser console as a warning instead.

Each message names the collection, file and field it applies to, so you can go straight to the line that needs changing:

Blog collection, seo.score field: The min option must be a number.

Two sets of checks run. The first validates the whole configuration against the same JSON schema your editor uses, published alongside the CMS version you’re running. It catches wrong value types, values outside an allowed set, and missing required options. A custom field type registered with its own schema joins these checks, so the options it accepts are validated alongside the built-in ones.

The second covers the rules a schema can’t express — mostly mistakes that wouldn’t fail at all otherwise, but would quietly give you an empty collection, a random slug or a validation rule that never runs:

  • Backend: a missing or misspelled backend name, a repo that isn’t in the owner/repo format, a missing OAuth client ID, an empty auth_methods list, or Open Authoring without Editorial Workflow
  • Site-wide options: a site_url that isn’t an absolute URL, a sanitize_replacement slug option that itself contains a character slugs can’t have, an empty i18n.locales list, a default_locale or initial_locales entry that isn’t one of the locales, or a collection or file i18n option with no site-level i18n to build on
  • Internationalization: an i18n option that leaves nothing to translate — a site-level configuration that no collection or singleton enables with its own i18n option, an entry collection or collection file with i18n enabled but no field with i18n: true (or translate) or i18n: duplicate, or a file collection with i18n enabled but none of its files
  • Collections: duplicate or invalid collection, file, field and variable type names, a collection with none of folder, files or divider or more than one of them, a collection without fields, a configuration where every collection is hidden, and a mismatch between format and extension
  • Entry naming: an identifier_field that names no field, a collection with neither a title field nor an identifier_field or slug option, a slug template containing slashes, and slug, path, summary, thumbnail and preview_path options that refer to fields that don’t exist
  • Entry lists: a filter on an undefined field, with neither a value nor a pattern, or with a pattern that isn’t a valid regular expression; sortable_fields, view_groups and view_filters that refer to undefined fields; a view_groups or view_filters default that names no group or filter; a reorder group that isn’t defined
  • Fields: mutually exclusive options such as field, fields and types, an explicitly empty fields or types list, a validation pattern that isn’t a valid regular expression, a min above the max or a minlength above the maxlength, a Number step of zero or less, Select fields with no options or duplicate option values, and conflicting DateTime timezone options
  • Default values: a default whose shape doesn’t match the field’s other options — a Select default that isn’t among the options; a Select, Relation, File or Image default that is an array without multiple or a single value with it; a Number default that isn’t a number of the value_type; a Code default object with output_code_only or with a property that isn’t one of the keys; a List or Object default with an object where a plain value is expected or the other way round, a property that names no subfield, or a missing or unknown variable type
  • References between fields: a Relation field whose collection or file doesn’t exist, or whose value_field, display_fields, search_fields or filters name fields the referenced collection doesn’t have; a Compute value template that names an undefined field; a List or Object thumbnail that names an undefined subfield, or one that isn’t an Image or File field
  • Options that Sveltia CMS doesn’t support, including deprecated camel case options such as valueField

An option name the schema doesn’t define is a warning rather than an error, so that a configuration carrying leftovers from Netlify/Decap CMS — or options from a newer release — keeps working. The option has no effect, and the console says so:

Blog collection: The filter.Tutorial option is not defined in the Sveltia CMS configuration schema. It will be ignored. Check for a typo or a syntax mistake.

A misspelled name is the obvious way to get one of these, but not the only one, which is why the console is worth a look whenever an option seems to do nothing. A YAML flow mapping quietly turns a comma-separated list into extra keys:

yaml
# `Tutorial` becomes an option of its own, and only `News` is matched
filter: { field: category, value: News, Tutorial }
# What was meant, with `value` holding both values
filter: { field: category, value: [News, Tutorial] }

Editor validation is still worth setting up

JSON schema validation in your editor reports an unknown option as you type, before the CMS ever loads the file.

Copyright © 2026 Kohei Yoshino