---
url: /en/docs/collections/files.md
description: >-
  Configure file collections in Sveltia CMS for managing pre-defined documents
  and standalone content.
---

# 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 add new files or delete existing ones. A listed file that doesn’t exist yet is created when it’s first saved. 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:

::: code-group

```yaml [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 [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 [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 [JavaScript]
{
  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.
* `label_singular`: A human-readable singular name for the collection. Optional. Used in the editor title when a file that doesn’t exist yet is being created.
* `description`: A brief description of the collection, displayed in the UI. Optional. Basic Markdown formatting is supported.
* `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.
* `hide`: Whether to hide the collection from the UI. Optional. See [Hiding the Collection](/en/docs/collections/entries/operations#hiding-the-collection).
* `format`, `frontmatter_delimiter`, `body_field`: The default file format options for the files in the collection. Optional. Each file can override them. [See below](#file-format-and-extension) for details.
* `media_folder`, `public_folder`: Media folder options for the collection. Optional. See [Collection-Level Configuration](/en/docs/media/internal#collection-level-configuration).
* `i18n`: I18n options for the collection. Optional. Each file also needs its own `i18n` option to be localized. See [Collection-Level Configuration](/en/docs/i18n/options#collection-level-configuration).
* `editor`: Content Editor options, such as `preview: false` to disable the preview pane. Optional. See [Disabling Previews](/en/docs/ui/content-editor#collection-level).
* `publish_mode`: The publish mode for the collection, overriding the top-level option. Optional. See [Enabling the Workflow per Collection](/en/docs/workflows/editorial#enabling-the-workflow-per-collection).
* `publish`: Set to `false` to hide the publishing controls in Editorial Workflow. Optional. See [Restricting Publishing and Deletion](/en/docs/workflows/editorial#restricting-publishing-and-deletion).
* `readonly`: Set to `true` to make every file in the collection read-only. Optional. See [Making Content Read-Only](/en/docs/collections/entries/operations#making-content-read-only).

Unlike entry collections, the collection-level `preview_path` and `preview_path_date_field` options don’t apply to file collections. Set them on each file instead.

### 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](#file-format-and-extension) for details.
* `frontmatter_delimiter`: The front matter delimiter. Optional. [See below](#front-matter-delimiter) for details.
* `body_field`: The body field options for front matter formats. Optional. [See below](#body-field-for-front-matter-formats) for details.
* `fields`: An array of field definitions for the file content. Required.
* `media_folder`, `public_folder`: Media folder options for the file, overriding the top-level and collection-level options. Optional. See [File-Level Configuration](/en/docs/media/internal#file-level-configuration).
* `i18n`: I18n options for the file. Optional. See [File-Level Configuration](/en/docs/i18n/options#file-level-configuration).
* `editor`: Content Editor options for the file, overriding the collection-level options. Optional. See [Disabling Previews](/en/docs/ui/content-editor#file-level).
* `readonly`: Set to `true` to make the file read-only, while the other files in the collection stay editable. Optional. See [Making Content Read-Only](/en/docs/collections/entries/operations#making-content-read-only).
* `preview_path`, `preview_path_date_field`: The file’s URL path on the live site. Optional. [See below](#preview-path) for details.

A listed file doesn’t have to exist in the repository. If it’s missing, the Content Editor opens with empty fields (or their default values), and the file is created when the editor saves it.

## 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 the `frontmatter` format, which detects YAML, TOML or JSON front matter automatically; a new file is saved with YAML front matter. For other extensions, it uses the corresponding format (e.g., `.yaml` uses `yaml` format). See [Default Format and Extension](/en/docs/collections/entries/formats#default-format-and-extension) for the full list.

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

::: code-group

```yaml [YAML]{7,13}
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 [TOML]{8,22}
[[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 [JSON]{10,19}
{
  "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 [JavaScript]{10,19}
{
  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:

::: code-group

```yaml [YAML]{4}
collections:
  - name: pages
    label: Pages
    format: json-frontmatter
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
```

```toml [TOML]{4}
[[collections]]
name = "pages"
label = "Pages"
format = "json-frontmatter"

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

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

```js [JavaScript]{6}
{
  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](/en/docs/how-tos#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](/en/docs/collections/entries/formats#front-matter-delimiter) 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:

::: code-group

```yaml [YAML]{8-9}
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        format: toml-frontmatter
        frontmatter_delimiter: ~~~
```

```toml [TOML]{9-10}
[[collections]]
name = "pages"
label = "Pages"

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

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

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

:::

### Body Field for Front Matter Formats

When using front matter formats (e.g., `yaml-frontmatter`, `toml-frontmatter`, `json-frontmatter`), you can configure the body field to specify where the main content of the file should be stored. By default, the body field is named `body`, but you can customize this by setting the `body_field` option at either the collection or file level.

See [Body Field for Front Matter Formats](/en/docs/collections/entries/formats#body-field-for-front-matter-formats) in the entry collections documentation for more details.

## Preview Path

A file has no preview link by default. To link it to its page on the live site, or on a [deploy preview](/en/docs/workflows/deploy-previews), set the `preview_path` option on the file. It works like the collection-level [`preview_path` option](/en/docs/collections/entries/previews#preview-paths) of an entry collection, with the following differences:

* `{{slug}}` is the file’s `name` option value.
* `{{dirname}}` is the directory of the `file` path, relative to the repository’s root directory, since a file collection has no `folder`.
* Field values, date/time tags, `{{filename}}`, `{{extension}}` and `{{locale}}` are filled in the same way, using the file’s own `fields`. The date/time tags use the file’s first DateTime field unless `preview_path_date_field` is set.

::: code-group

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

```toml [TOML]{9}
[[collections]]
name = "pages"
label = "Pages"

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

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

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

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

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

:::

## 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](/en/docs/collections/singletons) for more details.