Sveltia CMS

Appearance

File Collections ​

A file collection contains pre-defined files, each representing a single piece of content. Editors can edit the content of these files but cannot create or delete them. Typical use cases for file collections include site settings, homepage content or about pages.

Creating a File Collection ​

The example below defines a file collection for managing static pages:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
      ],
    },
  ],
}

Each file in the collection is defined with a name, label, file path, and a set of fields. Editors can modify the content of these files through the Sveltia CMS interface.

Collection Options ​

A file collection supports the following options:

  • name: A unique identifier for the collection. Required.
  • label: A human-readable name for the collection. Optional.
  • icon: A Material Symbols icon name to represent the collection in the CMS UI. Optional.
  • files: An array of file definitions within the collection. Required.

File Options ​

A file definition within a file collection supports the following options:

  • name: A unique identifier for the file within the collection. Required.
  • label: A human-readable name for the file. Optional.
  • icon: A Material Symbols icon name to represent the file in the CMS UI. Optional.
  • file: The path to the file in the content repository. Required.
  • format: The file format (e.g., yaml, json, toml, yaml-frontmatter, etc.). Optional. See below for details.
  • fields: An array of field definitions for the file content. Required.

File Format and Extension ​

The file format and extension for each file in a file collection can be customized using the format property within each file definition. Sveltia CMS supports various file formats, including Markdown, YAML, JSON, and TOML.

By default, file format is determined based on the file extension. If it is a Markdown file (e.g., .md), it uses yaml-frontmatter format. For other extensions, it uses the corresponding format (e.g., .yaml uses yaml format).

To illustrate, here is a file collection with two files using different formats:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.json
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
      - name: contact
        label: Contact Page
        file: content/pages/contact.yaml
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.json"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"

[[collections.files]]
name = "contact"
label = "Contact Page"
file = "content/pages/contact.yaml"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.json",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        },
        {
          "name": "contact",
          "label": "Contact Page",
          "file": "content/pages/contact.yaml",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.json",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
        {
          name: "contact",
          label: "Contact Page",
          file: "content/pages/contact.yaml",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
      ],
    },
  ],
}

Format ​

To explicitly set the file format, you can add the format property to each file definition. This is useful if you want to use TOML or JSON formats for Markdown files. Here is an example:

yaml
collections:
  - name: pages
    label: Pages
    format: json-frontmatter
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
toml
[[collections]]
name = "pages"
label = "Pages"
format = "json-frontmatter"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "format": "json-frontmatter",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md"
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      format: "json-frontmatter",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
        },
      ],
    },
  ],
}

The format can be set at the collection level to apply to all files within that collection, or at the individual file level to override the collection setting for specific files.

Note that when specifying a format, ensure that the file extension matches the chosen format to avoid confusion. If there is an obvious mismatch between the file extension and the specified format, Sveltia CMS will raise a validation error.

Extension ​

Unlike entry collections, file collections do not support the extension option to define allowed file extensions, since each file is pre-defined with a specific path containing its extension.

Extension-less files are supported in file collections. When using extension-less files, it is recommended to explicitly set the format property to ensure the correct parsing of the file content. If format is not set, it defaults to yaml-frontmatter.

See Editing site deployment configuration files in our how-tos for an example of using extension-less files in a file collection.

Front Matter Delimiter ​

As with entry collections, the frontmatter_delimiter option can also be used to customize the front matter delimiter for Markdown files, either at the collection or file level. Here is an example of setting both format and frontmatter_delimiter at the file level:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        format: toml-frontmatter
        frontmatter_delimiter: ~~~
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"
format = "toml-frontmatter"
frontmatter_delimiter = "~~~"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md",
          "format": "toml-frontmatter",
          "frontmatter_delimiter": "~~~"
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
          format: "toml-frontmatter",
          frontmatter_delimiter: "~~~",
        },
      ],
    },
  ],
}

Singletons ​

The singleton collection is a special type of file collection that allows you to manage a set of pre-defined files without the ability to create or delete them. Singletons are useful for managing site-wide settings or content that should only exist as a single instance. See Singletons for more details.

Released under the MIT License.

Copyright © 2026 Kohei Yoshino