Collections Configuration

collections accepts a list of collection objects, each with the following options

Identifier Field

Static CMS expects every entry to provide a field named "title" that serves as an identifier for the entry. The identifier field serves as an entry's title when viewing a list of entries, and is used in slug creation. If you would like to use a field other than "title" as the identifier, you can set identifier_field to the name of the other field.

collections:
  - name: posts
    identifier_field: name

Extension and Format

These settings determine how collection files are parsed and saved. Both are optional—Static CMS will attempt to infer your settings based on existing items in the collection. If your collection is empty, or you'd like more control, you can set these fields explicitly.

extension determines the file extension searched for when finding existing entries in a folder collection and it determines the file extension used to save new collection items. It accepts the following values: yml, yaml, json, md, markdown, mdx, html.

You may also specify a custom extension not included in the list above, as long as the collection files can be parsed and saved in one of the supported formats below.

format determines how collection files are parsed and saved. It will be inferred if the extension field or existing collection file extensions match one of the supported extensions above. It accepts the following values:

• yml or yaml: parses and saves files as YAML-formatted data files; saves with yml extension by default
• json: parses and saves files as JSON-formatted data files; saves with json extension by default
• toml: parses and saves files as TOML-formatted data files; saves with toml extension by default
• frontmatter: parses files and saves files with data frontmatter followed by an unparsed body text (edited using a body field); saves with md extension by default; default for collections that cannot be inferred. Collections with frontmatter format (either inferred or explicitly set) can parse files with frontmatter in YAML or JSON format. However, they will be saved with YAML frontmatter.
• yaml-frontmatter: same as the frontmatter format above, except frontmatter will be both parsed and saved only as YAML, followed by unparsed body text. The default delimiter for this option is ---.
• json-frontmatter: same as the frontmatter format above, except frontmatter will be both parsed and saved as JSON, followed by unparsed body text. The default delimiter for this option is { }.
• toml-frontmatter: same as the frontmatter format above, except frontmatter will be both parsed and saved only as TOML, followed by unparsed body text. The default delimiter for this option is +++.

Frontmatter Delimiter

If you have an explicit frontmatter format declared, the frontmatter_delimiter option allows you to specify a custom delimiter like ~~~. If you need different beginning and ending delimiters, you can use an array like ["(", ")"].

Slug

For folder collections where users can create new items, the slug option specifies a template for generating new filenames based on a file's creation date and title field. (This means that all collections with create: true must have a title field (a different field can be used via identifier_field).

The slug template can also reference a field value by name, eg. {{title}}. If a field name conflicts with a built in template tag name - for example, if you have a field named slug, and would like to reference that field via {{slug}}, you can do so by adding the explicit fields. prefix, eg. {{fields.slug}}.

Available Template Tags

• Any field can be referenced by wrapping the field name in double curly braces, eg. {{author}}
• {{slug}}: a url-safe version of the title field (or identifier field) for the file
• {{year}}: 4-digit year of the file creation date
• {{month}}: 2-digit month of the file creation date
• {{day}}: 2-digit day of the month of the file creation date
• {{hour}}: 2-digit hour of the file creation date
• {{minute}}: 2-digit minute of the file creation date
• {{second}}: 2-digit second of the file creation date

Examples

Basic Example

slug: '{{year}}-{{month}}-{{day}}_{{slug}}'

Field Names

slug: '{{year}}-{{month}}-{{day}}_{{title}}_{{some_other_field}}'

Field Name That Conflicts With Template Tag

slug: '{{year}}-{{month}}-{{day}}_{{fields.slug}}'

Fields

Ignored if Files Collection

The fields option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in your Static CMS config file determines their order in the editor UI and in the saved file.

fields accepts a list of widgets. See widgets for more details.

In files with frontmatter, one field should be named body. This special field represents the section of the document (usually markdown) that comes after the frontmatter.

fields:
  - label: "Title"
    name: "title"
    widget: "string"
    pattern: ['.{20,}', "Must have at least 20 characters"]
  - {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
  - {label: "Featured Image", name: "thumbnail", widget: "image", required: false}
  - {label: "Body", name: "body", widget: "markdown", comment: 'This is a multiline\ncomment' }

Editor

The editor setting changes options for the editor view of a collection or a file inside a files collection. It has the following options:

editor:
  preview: false
  frame: false

Note: Setting this as a top level configuration will set the default for all collections

Summary

The summary setting allows the customization of the collection table view. Similar to the slug field, a string with templates can be used to include values of different fields, e.g. {{title}}. This option over-rides the default of title field and identifier_field.

Available Template Tags

Template tags are the same as those for slug, with the following additions:

• {{dirname}} The path to the file's parent directory, relative to the collection's folder.
• {{filename}} The file name without the extension part.
• {{extension}} The file extension.
• {{commit_date}} The file commit date on supported backends (git based backends).
• {{commit_author}} The file author date on supported backends (git based backends).

summary: 'Version: {{version}} - {{title}}'

Template Transformations

You can apply transformations on fields in a summary string template using filter notation syntax.

Example config:

collections:
  - name: 'posts'
    label: 'Posts'
    folder: '_posts'
    summary: "{{title | upper}} - {{date | date('yyyy-MM-dd')}} - {{body | truncate(20, '***')}}"
    fields:
      - { label: 'Title', name: 'title', widget: 'string' }
      - { label: 'Publish Date', name: 'date', widget: 'datetime' }
      - { label: 'Body', name: 'body', widget: 'markdown' }

The above config will transform the title field to uppercase and format the date field using yyyy-MM-dd format. Available transformations are:

Sortable Fields

The sortable_fields setting is an optional object with the following options:

Defaults to inferring title, date, author and description fields and will also show Update On sort field in git based backends.

When author field cannot be inferred commit author will be used.

# use dot notation for nested fields
sortable_fields:
  fields: ['commit_date', 'title', 'commit_author', 'language.en']

Default Sort

# use dot notation for nested fields
sortable_fields:
  fields: ['commit_date', 'title', 'commit_author', 'language.en']
  default:
    field: commit_date
    direction: Descending

View Filters

The view_filters setting is an optional property which takes a list of predefined view filters to show in the UI and an optional default view filter.

view_filters:
  default: drafts
  filters:
    - name: alice-and-bob
      label: "Alice's and Bob's Posts"
      field: author
      pattern: 'Alice|Bob'
    - name: posts-2020
      label: 'Posts published in 2020'
      field: date
      pattern: '2020'
    - name: drafts
      label: Drafts
      field: draft
      pattern: true

View Groups

The view_groups setting is an optional property which takes a list of predefined view groups to show in the UI and an optional default view group.

view_groups:
  default: by-year
  groups:
    - name: by-year
      label: Year
      field: date
      # groups items based on the value matched by the pattern
      pattern: \d{4}
    - name: drafts
      label: Drafts
      field: draft

Media Library

The media_library settings allows customization of the media library at the collection level.

Options

Example

media_library:
  max_file_size: 512000
  folder_support: true