Beta Features

Features on this page may be broken or may not function as expected. We are working to test and fix the features as well as update the docs. Use at your own risk.

Static CMS runs new functionality in an open beta format from time to time. That means that this functionality is totally available for use, an it might be ready for primetime, but it could break or change without notice.

Use these features at your own risk.

i18n Support

The CMS can provide a side by side interface for authoring content in multiple languages. Configuring the CMS for i18n support requires top level configuration, collection level configuration and field level configuration.

Top level configuration

i18n:
  # Required and can be one of multiple_folders, multiple_files or single_file
  # multiple_folders - persists files in `<folder>/<locale>/<slug>.<extension>`
  # multiple_files - persists files in `<folder>/<slug>.<locale>.<extension>`
  # single_file - persists a single file in `<folder>/<slug>.<extension>`
  structure: multiple_folders

# Required - a list of locales to show in the editor UI

locales: [en, de, fr]

# Optional, defaults to the first item in locales.

# The locale to be used for fields validation and as a baseline for the entry.

defaultLocale: en

Collection level configuration

collections:
  - name: i18n_content
    # same as the top level, but all fields are optional and defaults to the top level
    # can also be a boolean to accept the top level defaults
    i18n: true

When using a file collection, you must also enable i18n for each individual file:

collections:
  - name: pages
    label: Pages
    # Configure i18n for this collection.
    i18n:
      structure: single_file
      locales: [en, de, fr]
    files:
      - name: about
        label: About Page
        file: site/content/about.yml
        # Enable i18n for this file.
        i18n: true
        fields:
          - { label: Title, name: title, widget: string, i18n: true }

Field level configuration

fields:
  - label: Title
    name: title
    widget: string
    # same as 'i18n: translate'. Allows translation of the title field
    i18n: true
  - label: Date
    name: date
    widget: datetime
    # The date field will be duplicated from the default locale.
    i18n: duplicate
  - label: Body
    name: body
    # The markdown field will be omitted from the translation.
    widget: markdown

Example configuration:

i18n:
  structure: multiple_folders
  locales: [en, de, fr]

collections:
  - name: posts
    label: Posts
    folder: content/posts
    create: true
    i18n: true
    fields:
      - label: Title
        name: title
        widget: string
        i18n: true
      - label: Date
        name: date
        widget: datetime
        i18n: duplicate
      - label: Body
        name: body
        widget: markdown

Limitations

File collections support only structure: single_file.
List widgets only support i18n: true. i18n configuration on sub fields is ignored.
Object widgets only support i18n: true and i18n configuration should be done per field:

- label: 'Object'
  name: 'object'
  widget: 'object'
  i18n: true
  fields:
    - { label: 'String', name: 'string', widget: 'string', i18n: true }
    - { label: 'Date', name: 'date', widget: 'datetime', i18n: duplicate }
    - { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: duplicate }
    - {
        label: 'Object',
        name: 'object',
        widget: 'object',
        i18n: true,
        field: { label: 'String', name: 'string', widget: 'string', i18n: duplicate },
      }

Folder Collections Path

See Folder Collections Path.

Nested Collections

Seed Nested Collections.

Commit Message Templates

You can customize the templates used by Static CMS to generate commit messages by setting the commit_messages option under backend in your Static CMS config.

Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, {{path}} will include the full path to the file changed.

Setting up your Static CMS config to recreate the default values would look like this:

backend:
  commit_messages:
    create: Create {{collection}} "{{slug}}"
    update: Update {{collection}} "{{slug}}"
    delete: Delete {{collection}} "{{slug}}"
    uploadMedia: Upload "{{path}}"
    deleteMedia: Delete "{{path}}"

Static CMS generates the following commit types:

Commit type	When is it triggered?	Available template tags
`create`	A new entry is created	`slug`, `path`, `collection`, `author-login`, `author-name`
`update`	An existing entry is changed	`slug`, `path`, `collection`, `author-login`, `author-name`
`delete`	An existing entry is deleted	`slug`, `path`, `collection`, `author-login`, `author-name`
`uploadMedia`	A media file is uploaded	`path`, `author-login`, `author-name`
`deleteMedia`	A media file is deleted	`path`, `author-login`, `author-name`

Template tags produce the following output:

{{slug}}: the url-safe filename of the entry changed
{{collection}}: the name of the collection containing the entry changed
{{path}}: the full path to the file changed
{{message}}: the relevant message based on the current change (e.g. the create message when an entry is created)
{{author-login}}: the login/username of the author
{{author-name}}: the full name of the author (might be empty based on the user's profile)

You can set a limit to as what the maximum file size of a file is that users can upload directly into a image field.

Example config:

- label: 'Featured Image'
  name: 'thumbnail'
  widget: 'image'
  default: '/uploads/chocolate-dogecoin.jpg'
  media_library:
    config:
      max_file_size: 512000 # in bytes, only for default media library

Summary string 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 upper, lower, date('<format>'), default('defaultValue'), ternary('valueForTrue','valueForFalse') and truncate(<number>)/truncate(<number>, '<string>')

Registering to CMS Events

You can execute a function when a specific CMS event occurs.

Example usage:

CMS.registerEventListener({
  name: 'prePublish',
  handler: ({ author, entry }) => console.info(JSON.stringify({ author, data: entry.data })),
});

Supported events are prePublish, postPublish, preSave and postSave. The preSave hook can be used to modify the entry data like so:

CMS.registerEventListener({
  name: 'preSave',
  handler: ({ entry }) => {
    return entry.data.set('title', 'new title');
  },
});