Static CMS
Star StaticJsCMS/static-cms on GitHub
DocsContributingCommunity

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 the 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.

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

Media library integrations are configured via the media_library property, and its value should be an object with at least a name property. A config property can also be used for options that should be passed to the library in use.

Example:

media_library:
  name: uploadcare
  config:
    publicKey: demopublickey

Site URL

The site_url setting should provide a URL to your published site. May be used by the 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 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

When the logo_url setting is specified, the CMS UI will change the logo displayed at the top of the login page, allowing you to brand the 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

The CMS locale. Defaults to en.

Other languages than English must be registered manually.

Example

In your config:

locale: 'de'

And in your custom JavaScript code:

import CMS, { de } from '@staticcms/core';

CMS.registerLocale('de', 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).

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.