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. It also provides information on using AI tools to assist with configuration.

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.

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:

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

Shorthand Notation

Sometimes we use shorthand notation for brevity. For example,

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

is the same as

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:

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

Multiline Strings

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

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:

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:

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

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

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

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

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

"$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:

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

For JSON files:

"json.schemas": [
  {
    "fileMatch": ["/static/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 Astro, the file is typically located in the /public/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 performs runtime validation of the configuration file when the CMS initializes. If there are any errors in the configuration, they will be displayed on the login screen.

This helps catch issues early and ensures that the CMS operates with a valid configuration, preventing potential runtime errors. The runtime validation includes checks for:

• Common backend misconfigurations
• File format and extension mismatches
• Invalid or duplicate collection or field names
• Mutually exclusive config options
• Invalid references in Relation fields

Unfinished feature

Comprehensive runtime validation is still under development and may not cover all configuration options yet. We recommend using JSON schema validation in your code editor for the most reliable feedback while editing the configuration file.

AI Tools Support

We provide standard llms.txt files to help AI tools understand the structure and syntax of the Sveltia CMS configuration. Generated from this documentation site, these files can be used with AI code assistants, such as GitHub Copilot, ChatGPT, Claude, and others, to enhance their ability to help you write and edit the configuration file.

Work-in-Progress

This site is still under development, and the documentation may contain inaccurate or incomplete information. The llms.txt files are automatically generated from the documentation site, so they may also contain errors or omissions. We’ll continue to improve the documentation and the llms.txt files over time.

Available llms.txt Files

There are two versions of the Sveltia CMS documentation available as llms.txt files:

• llms.txt: A sitemap-style version of the documentation, including the title and description of each page. (3k+ tokens)

  https://sveltiacms.app/llms.txt

• llms-full.txt: A complete version of the documentation, including all page content, code examples, and details. (200k+ tokens)

  https://sveltiacms.app/llms-full.txt

Using the llms.txt Files

If you use GitHub Copilot in VS Code, you can use the #fetch tool in the chat interface to load the llms.txt file as context:

#fetch https://sveltiacms.app/llms.txt

If you use Cursor, you can add the llms.txt file using the @docs feature.

For other AI tools, refer to their documentation on how to add custom knowledge sources or context files.