Configuration File

All configuration options for Netlify 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">

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 Netlify 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 Netlify CMS config.yml 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, currently in beta.

Publish Mode

By default, all entries created or edited in the Netlify CMS are committed directly into the main repository branch.

The publish_mode option allows you to enable “Editorial Workflow” mode for more control over the content publishing phases. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live.

Note: Editorial workflow works with GitHub repositories, and support for GitLab and Bitbucket is in beta.

You can enable the Editorial Workflow with the following line in your Netlify CMS config.yml file:

# /admin/config.yml
publish_mode: editorial_workflow

From a technical perspective, the workflow translates editor UI actions into common Git commands:

Actions in Netlify UI Perform these Git actions
Save draft Commits to a new branch (named according to the pattern cms/collectionName/entrySlug), and opens a pull request
Edit draft Pushes another commit to the draft branch/pull request
Approve and publish draft Merges pull request and deletes branch

Media and Public Folders

Netlify 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 without the protocol portion (e.g., 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.yml:

locale: 'de'

And in your custom JavaScript code:

import CMS from 'netlify-cms-app';
import { de } from 'netlify-cms-locales';

CMS.registerLocale('de', de);

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

When importing netlify-cms all locales are registered by default (so you only need to update your config.yml).

Deploy preview links can be disabled by setting show_preview_links to false.

Example:

show_preview_links: false

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:

Example

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

Collections

This setting is required.

The collections setting is the heart of your Netlify 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 Netlify CMS config.yml file.

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

The last few options require more detailed information.

identifier_field

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

Example

collections:
  - name: posts
    identifier_field: name

extension and format

These settings determine how collection files are parsed and saved. Both are optional—Netlify 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, toml, json, md, markdown, 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:

frontmatter_delimiter

If you have an explicit frontmatter format declared, this 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. . 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, you can do so by adding the explicit fields. prefix, eg. ``.

Available template tags:

Example:

slug: "--_"

Example using field names:

slug: "--__"

Example using field name that conflicts with a template tag:

slug: "--_"

preview_path

A string representing the path where content in this collection can be found on the live site. This allows deploy preview links to direct to lead to a specific piece of content rather than the site root of a deploy preview.

Available template tags:

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

Examples:

collections:
  - name: posts
    preview_path: "blog///"

collections:
  - name: posts
    preview_path: "blog///."

preview_path_date_field

The name of a date field for parsing date-based template tags from preview_path. If this field is not provided and preview_path contains date-based template tags (eg. ``), Netlify CMS will attempt to infer a usable date field by checking for common date field names, such as date. If you find that you need to specify a date field, you can use preview_path_date_field to tell Netlify CMS which field to use for preview path template tags.

Example:

collections:
  - name: posts
    preview_path_date_field: "updated_on"

fields

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

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

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.

Example:

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

This setting changes options for the editor view of a collection or a file inside a files collection. It has one option so far:

Example:

  editor:
     preview: false

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

summary

This setting allows the customization of the collection list view. Similar to the slug field, a string with templates can be used to include values of different fields, e.g. ``. 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:

Example

    summary: "Version:  - "

sortable_fields

An optional list of sort fields to show in the UI.

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

When author field can’t be inferred commit author will be used.

Example

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

view_filters

An optional list of predefined view filters to show in the UI.

Defaults to an empty list.

Example

    view_filters:
      - label: "Alice's and Bob's Posts"
        field: author
        pattern: 'Alice|Bob'
      - label: 'Posts published in 2020'
        field: date
        pattern: '2020'
      - label: Drafts
        field: draft
        pattern: true

view_groups

An optional list of predefined view groups to show in the UI.

Defaults to an empty list.

Example

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