Configuration Options

All configuration options for Static CMS are specified in a config.yml file, in the folder where you access the editor UI (usually in the /admin folder).

Alternatively, you can specify a custom config file using a link tag:

<!-- Note the "type" and "rel" attribute values, which are required. -->
<link href="path/to/config.yml" type="text/yaml" rel="cms-config-url" />

If you prefer, you can use a javascript file (admin/config.js) instead of a yaml file. Simply import the javascript config and pass it into your CMS.init({ config }) call.

To see working configuration examples, you can start from a template or check out the CMS demo site. (No login required: click the login button and Static CMS will open.) You can refer to the demo configuration code to see how each option was configured.

You can find details about all configuration options below. Note that YAML syntax allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.

Backend

This setting is required.

The backend option specifies how to access the content for your site, including authentication. Full details and code samples can be found in Backends.

Note: no matter where you access Static CMS — whether running locally, in a staging environment, or in your published site — it will always fetch and commit files in your hosted repository (for example, on GitHub), on the branch you configured in your Static CMS config file. This means that content fetched in the admin UI will match the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI will save directly to the hosted repository, even if you're running the UI locally or in staging. If you want to have your local CMS write to a local repository, try the local_backend setting.

Commit Message Templates

You can customize the templates used by Static CMS to generate commit messages by setting the commit_messages option.

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.

Example

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

Commit Types

Static CMS generates the following commit types:

Template Tags

Template tags produce the following output:

• {{slug}}: url-safe filename of the changed entry
• {{collection}}: name of the collection containing the changed entry
• {{path}}: full path to the changed file
• {{author-login}}: login/username of the author
• {{author-name}}: full name of the author (might be empty based on the user's profile)

Media and Public Folders

Static CMS users can upload files to your repository using the Media Gallery. The following settings specify where these files are saved, and where they can be accessed on your built site.

Media Folder

This setting is required.

The media_folder option specifies the folder path where uploaded files should be saved, relative to the base of the repo.

media_folder: "static/images/uploads"

Public Folder

The public_folder option specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site. For fields controlled by [file] or [image] widgets, the value of the field is generated by prepending this path to the filename of the selected file. Defaults to the value of media_folder, with an opening / if one is not already included.

public_folder: "/images/uploads"

Based on the settings above, if a user used an image widget field called avatar to upload and select an image called philosoraptor.png, the image would be saved to the repository at /static/images/uploads/philosoraptor.png, and the avatar field for the file would be set to /images/uploads/philosoraptor.png.

This setting can be set to an absolute URL e.g. https://netlify.com/media should you wish, however in general this is not advisable as content should have relative paths to other content.

Media Library

Beta Feature

The media_library settings allows customization of the media library.

Options

Example

media_library:
  max_file_size: 512000
  folder_support: true

Site URL

The site_url setting should provide a URL to your published site. May be used by Static CMS for various functionality. Used together with a collection's preview_path to create links to live content.

Example:

site_url: https://your-site.com

Display URL

When the display_url setting is specified, the Static CMS UI will include a link in the fixed area at the top of the page, allowing content authors to easily return to your main site. The text of the link consists of the URL with the protocol portion (e.g., https://your-site.com).

Defaults to site_url.

Example:

display_url: https://your-site.com

Custom Logo

When the logo_url setting is specified, the Static CMS UI will change the logo displayed at the top of the login page, allowing you to brand Static CMS with your own logo. logo_url is assumed to be a URL to an image file.

Example:

logo_url: https://your-site.com/images/logo.svg

Locale

Static CMS locale. Defaults to en.

Example

In your config:

locale: 'de'

When a translation for the selected locale is missing the English one will be used.

All locales are registered by default (so you only need to update your config).

Search

The search functionally requires loading all collection(s) entries, which can exhaust rate limits on large repositories. It can be disabled by setting the top level search property to false.

Defaults to true

Example:

search: false

Slug Type

The slug option allows you to change how filenames for entries are created and sanitized. It also applies to filenames of media inserted via the default media library.
For modifying the actual data in a slug, see the per-collection option below.

slug accepts multiple options:

• encoding

  • unicode (default): Sanitize filenames (slugs) according to RFC3987 and the WHATWG URL spec. This spec allows non-ASCII (or non-Latin) characters to exist in URLs.
  • ascii: Sanitize filenames (slugs) according to RFC3986. The only allowed characters are (0-9, a-z, A-Z, _, -, ~).

• clean_accents: Set to true to remove diacritics from slug characters before sanitizing. This is often helpful when using ascii encoding.

• sanitize_replacement: The replacement string used to substitute unsafe characters, defaults to -.

Example

slug:
  encoding: "ascii"
  clean_accents: true
  sanitize_replacement: "_"

Collections

This setting is required.

The collections setting is the heart of your Static CMS configuration, as it determines how content types and editor fields in the UI generate files and content in your repository. Each collection you configure displays in the left sidebar of the Content page of the editor UI, in the order they are entered into your Static CMS config file.

collections accepts a list of collection objects. See Collections for details.

Disable Local Backup

When the disable_local_backup setting is set to true local backups will no be taken for your entries and you will not be prompted to load local backups.