Overview

Start with a Template

Add to Your Site

CDN Hosting

Bundling

Configuration Options

Typescript

Beta Features

Intro

Getting Started

Updating Your CMS

How to Upgrade to v4

Decap / Netlify Migration Guide

Migration

Migration Guides

Git Gateway

GitHub

Bitbucket

GitLab

Gitea

Local Backend

Test Backend

Backends

Editorial Workflow

Open Authoring

Workflow

Collections Configuration

Collection Types

i18n Support

Collections

Boolean

Code

Color

DateTime

File

Hidden

Image

Key Value

List

Markdown

Number

Object

Relation

Select

String

Text

UUID

Widgets

Netlify Large Media

Media

Theming

Creating Custom Widgets

Creating Custom Previews

Custom Links & Pages

Adding Custom Icons

Events Hooks

Customization

Customizing Static CMS

Contributor Guide

Writing Style Guide

Examples

Contributing

Community

Available Widgets

Common widget options

Example Widget

Field Conditions

Widgets define the data type and interface for entry fields. Static CMS comes with several built-in widgets. Click the widget names in the sidebar to jump to specific widget details. You can also create your own!
Widgets are specified as collection fields in the Static CMS config file. 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.
To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on 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 field was configured.
Available Widgets
Common widget options
The following options are available on all fields:
Example Widget
Field Conditions
The fields can be shown conditionally based on the values of the other fields.
The condition option can take a single filter rule or a list of filter rules.
Example
The example below conditionally shows fields based on the values of other fields.
Nested Field Example
The example below conditionally shows fields based on the values of other nested fields.
List Field Example
The example below conditionally shows fields inside a list based on the values of other fields in the same list item. This works with both fields or types.

Backend Configuration

Creating a New Backend

A backend is JavaScript code that allows Static CMS to communicate with a service that stores content - typically a Git host like GitHub or GitLab. It provides functions that Static CMS can use to do things like read and update files using API's provided by the service.
Backend Configuration
Individual backends provide their own configuration documentation, but there are some configuration options that are common to multiple backends. A full reference is below. Note that these are properties of the backend field, and should be nested under that field.
Creating a New Backend
Anyone can write a backend, but the API is not yet finalized and documented. If you would like to write your own backend for a service that does not have one currently, Static CMS recommends using the GitHub backend as a reference for API and best practices.

Static CMS exposes a window.CMS global object that you can use to customize your CMS. The same object is also the default export if you import Static CMS as an npm module. Available options are:
Register custom widgets

Find out more

Static CMS is an open source content management system for your Git workflow that enables you to provide editors with a friendly UI. You can use it with any static site generator to create faster, more flexible web projects. Content is stored in your Git repository alongside your code for easier versioning and the option to handle content updates directly in Git.
At its core, Static CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub, GitLab, or Bitbucket APIs. This provides many advantages, including:
Fast, web-based UI: With rich-text editing, real-time preview, and drag-and-drop media uploads.
Find out more
Get a feel for the UI in the demo site. (No login required. Click the login button to go straight to the Static CMS editor UI.)

Access Static CMS

More paths to explore

You can add Static CMS to an existing site, but the quickest way to get started is with a template. Found below, our featured templates deploy a bare-bones site and Static CMS to Netlify, giving you a fully working CMS-enabled site with just a few clicks.
After clicking one of those buttons, authenticate with GitHub and choose a repository name. Netlify then automatically creates a clone of the repository in your GitHub account. Next, it builds and deploys the new site on Netlify, bringing you to the site dashboard after completing the build.
Note for GitLab and Bitbucket users: Static CMS supports GitLab and Bitbucket repositories, but will not work with the Deploy to Netlify buttons above without additional configuration (See GitLab or Bitbucket respectively).
Access Static CMS
Try adding and editing posts, or changing the content of the Products page. When you save, the changes are pushed immediately to your Git repository, triggering a build on Netlify, and updating the content on your site. Check out the configuration code by visiting your site repo.
More paths to explore
To see how to integrate Static CMS into an existing project, go to Add to your site.

CDN hosting

You can adapt Static CMS to a wide variety of projects. It works with any content written in markdown, JSON or YAML files, stored in a repo on GitHub, GitLab or Bitbucket. You can also create your own custom backend.
You can add Static CMS to your site in two different ways:
CDN hosting
Adding Static CMS via a public CDN to a site that is built with a common static site generator, like Jekyll, Hugo, Hexo, or Gatsby. Alternatively, is a quick and easy way to get started. You can start from a template or use this guide to get started.
Bundling
An alternative to CDN is directly bundling the StaticCMS package directly into your app. While this require extra setup steps, it give you the greatest level of control over your CMS. It also provides complete support for TypeScript, including for your config file.
See the bundling guide to get started.

App File Structure

Configuration

Authentication

Accessing Static CMS

This tutorial guides you through the steps for adding Static CMS via a public CDN to a site that is built with a common static site generator, like Jekyll, Next, Hugo, Hexo, or Gatsby. Alternatively, you can start from a template or dive right into configuration options.
App File Structure
A static admin folder contains all Static CMS files, stored at the root of your published site. Where you store this folder in the source files depends on your static site generator. Here is the static file location for a few of the most popular static site generators:
If your generator is not listed here, you can check its documentation, or as a shortcut, look in your project for a css or images folder. The contents of folders like that are usually processed as static files, so it is likely you can store your admin folder next to those. (When you have found the location, feel free to add it to these docs by filing a pull request!)
Inside the admin folder, you will create two files:
The first file, admin/index.html, is the entry point for the Static CMS admin interface. This means that users navigate to yoursite.com/admin/ to access it. On the code side, it is a basic HTML starter page that loads the Static CMS JavaScript file from a public CDN and initializes it. The second file, admin/config.yml, is the heart of your Static CMS installation, and a bit more complex. The Configuration section covers the details.
In this example, we pull the admin/index.html file from a public CDN.
In the code above the script is loaded from the unpkg CDN. Should there be any issue, jsDelivr can be used as an alternative source. Simply replace https://unpkg.com/ with https://cdn.jsdelivr.net/npm/
Configuration
Configuration is different for every site, so we will break it down into parts. Add all the code snippets in this section to your admin/config.yml file. Alternatively, 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.
Backend
We are using Netlify for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward.
For GitHub repositories, you can start your Static CMS config file with these lines:
The configuration above specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We will get to the details of that in the Authentication section below.) If you leave out the branch declaration, it defaults to main.
Editorial Workflow <BetaImage />
By default, saving a post in the CMS interface pushes a commit directly to the publication branch specified in backend. However, you also have the option to enable the Editorial Workflow, which adds an interface for drafting, reviewing, and approving posts. To do this, add the following line to your config.yml:
Media and Public Folders
Static CMS allows users to upload images directly within the editor. For this to work, Static CMS needs to know where to save them. If you already have an images folder in your project, you could use its path, possibly creating an uploads sub-folder, for example:
If you are creating a new folder for uploaded media, you will need to know where your static site generator expects static files. You can refer to the paths outlined above in App File Structure, and put your media folder in the same location where you put the admin folder.
Note that the media_folder file path is relative to the project root, so the example above would work for Jekyll, GitBook, or any other generator that stores static files at the project root. However, it would not work for Hugo, Next, Hexo, Middleman or others that store static files in a subfolder. Here is an example that could work for a Hugo site:
The configuration above adds a new setting, public_folder. While media_folder specifies where uploaded files are saved in the repo, public_folder indicates where they are found in the published site. Image src attributes use this path, which is relative to the file where it is called. For this reason, we usually start the path at the site root, using the opening /.
Collections
Collections define the structure for the different content types on your static site. Since every site is different, the collections settings differ greatly from one site to the next.
Let us say your site has a blog, with the posts stored in _posts/blog, and files saved in a date-title format, like 1999-12-31-lets-party.md. Each post begins with settings in yaml-formatted front matter, like so:
Given this example, our collections settings would look like this in your Static CMS config file:
Let us break that down:
As described above, the widget property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value is saved in the document front matter as the value for the name specified for that field. A full listing of available widgets can be found in the Widgets doc.
Based on this example, you can go through the post types in your site and add the appropriate settings to your Static CMS config file. Each post type should be listed as a separate node under the collections field. See the Collections reference doc for more configuration options.
Filter
The entries for any collection can be filtered based on the value of a single field. The example collection below only shows post entries with the value en in the language field.
Authentication
Now that you have your Static CMS files in place and configured, all that is left is to enable authentication. We are using the Netlify platform here because it is one of the quickest ways to get started, but you can learn about other authentication options in the Backends doc.
Setup on Netlify
Netlify offers a built-in authentication service called Identity. In order to use it, connect your site repo with Netlify.
Enable Identity and Git Gateway
Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:
Add the Netlify Identity Widget
With the backend set to handle authentication, now you need a frontend interface to connect to it. The open source Netlify Identity Widget is a drop-in widget made for just this purpose. To include the widget in your site, add the following script tag in two places:
Add this to the <head> of your CMS index page at /admin/index.html, as well as the <head> of your site's main index page. Depending on how your site generator is set up, this may mean you need to add it to the default template, or to a "partial" or "include" template. If you can find where the site stylesheet is linked, that is probably the right place. Alternatively, you can include the script in your site using Netlify's Script Injection feature.
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to Static CMS, redirect the user back to the /admin/ path. To do this, add the following script before the closing body tag of your site's main index page:
Note: This example script requires modern JavaScript and does not work on IE11. For legacy browser support, use function expressions (function () {}) in place of the arrow functions (() => {}), or use a transpiler such as Babel.
Accessing Static CMS
Your site CMS is now fully configured and ready for login!
If you set your registration preference to "Invite only," invite yourself (and anyone else you choose) as a site user. To do this, select the Identity tab from your site dashboard, and then select the Invite users button. Invited users receive an email invitation with a confirmation link. Clicking the link will take you to your site with a login prompt.
If you left your site registration open, or for return visits after confirming an email invitation, access your site's CMS at yoursite.com/admin/.
Note: No matter where you access Static CMS — whether running locally, in a staging environment, or in your published site — it always fetches and commits 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 matches the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI saves directly to the hosted repository, even if you are running the UI locally or in staging.
Happy posting!

Installation

This tutorial guides you through the steps for adding Static CMS via a package manager to a site that is built with a common static site generator. If you want to start form a template, the Next Template provides a great example of bundling in action.
Installation
To get started you need to install Static CMS via a package manager and save it to your project:
Then create a new route for your project (for instance at /admin), then import Static CMS and its styles:
The default export is a CMS object, which has an init method that takes an object with a config attribute. The config attribute is an object representing the configuration options. You can use destructuring assignment syntax as shorthand:
Note: Wherever you initialize Static CMS (via CMS.init()), it takes over the current page. Make sure you only run the initialization code on your CMS page.
If the CMS object is initialized without being passed an object with a valid config attribute, it will try to fetch and read a config.yml file, via http, within the same path where Static CMS resides (/admin/config.yml).
Note: Because config.yml is requested via http, make sure <siteurl>/admin/config.yml exists as an endpoint on your build. If the file is not placed in the public folder, this might not be the default behaviour for your static site generator.
Make sure the file containing the CMS object will be built as a page, with @staticcms/core bundled, and that the code including CMS.init() will run on the client. This is what might take some time, as it will be done differently based on your static site generator. Check your static site generators's documentation for further details.
Configuration
Configuration is different for every site, so we will break it down into parts. Add all the code snippets in this section to your admin/config.js file (which is passed into the CMS.init({ config }) call).
Backend
We are using Netlify for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward.
For GitHub and GitLab repositories, you can start your Static CMS config file with these lines:
The configuration above specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We will get to the details of that in the Authentication section below.) If you leave out the branch declaration, it defaults to main.
Editorial Workflow <BetaImage />
By default, saving a post in the CMS interface pushes a commit directly to the publication branch specified in backend. However, you also have the option to enable the Editorial Workflow, which adds an interface for drafting, reviewing, and approving posts. To do this, add the following line to your config.yml:
Media and Public Folders
Static CMS allows users to upload images directly within the editor. For this to work, Static CMS needs to know where to save them. If you already have an images folder in your project, you could use its path, possibly creating an uploads sub-folder, for example:
If you are creating a new folder for uploaded media, you will need to know where your static site generator expects static files. You can refer to the paths outlined above in App File Structure, and put your media folder in the same location where you put the admin folder.
Note that themedia_folder file path is relative to the project root, so the example above would work for Jekyll, GitBook, or any other generator that stores static files at the project root. However, it would not work for Hugo, Hexo, Middleman or others that store static files in a subfolder. Here is an example that could work for a Hugo site:
The configuration above adds a new setting, public_folder. While media_folder specifies where uploaded files are saved in the repo, public_folder indicates where they are found in the published site. Image src attributes use this path, which is relative to the file where it is called. For this reason, we usually start the path at the site root, using the opening /.
Collections
Collections define the structure for the different content types on your static site. Since every site is different, the collections settings differ greatly from one site to the next.
Let us say your site has a blog, with the posts stored in _posts/blog, and files saved in a date-title format, like 1999-12-31-lets-party.md. Each post begins with settings in yaml-formatted front matter, like so:
Given this example, our collections settings would look like this in your Static CMS config file:
Let us break that down:
As described above, the widget property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value is saved in the document front matter as the value for the name specified for that field. A full listing of available widgets can be found in the Widgets doc.
Based on this example, you can go through the post types in your site and add the appropriate settings to your Static CMS config file. Each post type should be listed as a separate node under the collections field. See the Collections reference doc for more configuration options.
Filter
The entries for any collection can be filtered based on the value of a single field. The example collection below only shows post entries with the value en in the language field.
Authentication
Now that you have your Static CMS files in place and configured, all that is left is to enable authentication. We are using the Netlify platform here because it is one of the quickest ways to get started, but you can learn about other authentication options in the Backends doc.
Setup on Netlify
Netlify offers a built-in authentication service called Identity. In order to use it, connect your site repo with Netlify.
Enable Identity and Git Gateway
Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:
Add the Netlify Identity Widget
With the backend set to handle authentication, now you need a frontend interface to connect to it. The open source Netlify Identity Widget is a drop-in widget made for just this purpose. To include the widget in your site, add the following script tag in two places:
Add this to the <head> of your CMS index page at /admin/index.html, as well as the <head> of your site's main index page. Depending on how your site generator is set up, this may mean you need to add it to the default template, or to a "partial" or "include" template. If you can find where the site stylesheet is linked, that is probably the right place. Alternatively, you can include the script in your site using Netlify's Script Injection feature.
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to Static CMS, redirect the user back to the /admin/ path. To do this, add the following script before the closing body tag of your site's main index page:
Note: This example script requires modern JavaScript and does not work on IE11. For legacy browser support, use function expressions (function () {}) in place of the arrow functions (() => {}), or use a transpiler such as Babel.
Accessing Static CMS
Your site CMS is now fully configured and ready for login!
If you set your registration preference to "Invite only," invite yourself (and anyone else you choose) as a site user. To do this, select the Identity tab from your site dashboard, and then select the Invite users button. Invited users receive an email invitation with a confirmation link. Clicking the link will take you to your site with a login prompt.
If you left your site registration open, or for return visits after confirming an email invitation, access your site's CMS at yoursite.com/admin/.
Note: No matter where you access Static CMS — whether running locally, in a staging environment, or in your published site — it always fetches and commits 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 matches the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI saves directly to the hosted repository, even if you are running the UI locally or in staging.
Happy posting!

Identifier Field

Extension and Format

Frontmatter Delimiter

Slug

Fields

Editor

Summary

Sortable Fields

View Filters

View Groups

Media Library

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.
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
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}}
Examples
Basic Example
Field Names
Field Name That Conflicts With Template Tag
Fields
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.
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:
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.
Template Transformations
You can apply transformations on fields in a summary string template using filter notation syntax.
Example config:
The above config will transform the title field to uppercase and format the date field using yyyy-MM-dd format.
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.
Default Sort
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 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.
Media Library
The media_library settings allows customization of the media library at the collection level.
Options
Example

Folder collections

File Collections

All editable content types are defined in the collections field of your config file, and display in the left sidebar of the Content page of the editor UI.
Collections come in two main types: folder and files.
Folder collections
Folder collections represent one or more files with the same format, fields, and configuration options, all stored within the same folder in the repository. You might use a folder collection for blog posts, product pages, author data files, etc.
Unlike file collections, folder collections have the option to allow editors to create new items in the collection. This is set by the boolean create field.
Note: Folder collections must have at least one field with the name title for creating new entry slugs. That field should use the default string widget. The label for the field can be any string value. If you wish to use a different field as your identifier, set identifier_field to the field name. See the Collections reference doc for details on how collections and fields are configured. If you forget to add this field, you will get an error that your collection "must have a field that is a valid entry identifier".
Examples
Basic
With Identifier Field
Filtered Folder Collections
The entries for any folder collection can be filtered based on the values of the fields or on file names. By filtering a folder into different collections, you can manage files with different fields, options, extensions, etc. in the same folder.
The filter option can take a single filter rule or a list of filter rules. There are two types of filter rules available: field and file.
Field Filter Rule
Filtered by Language
The example below creates two collections in the same folder, filtered by the language field. The first collection includes posts with language: en, and the second, with language: es.
Filtered by Nested Field
The example below creates a collection based on a nested field's value.
Filtered by Tags
The example below creates two collections in the same folder, filtered by the tags field. The first collection includes posts with the news or article tags, and the second, with the blog tag.
File Name Filter Rule
Filtered by Tags
The example below creates a collection containing only files named index.md exactly.
Folder Collections Path
By default Static CMS stores folder collection content under the folder specified in the collection setting.
For example configuring folder: posts for a collection will save the content under posts/post-title.md.
You can now specify an additional path template (similar to the slug template) to control the content destination.
This allows saving content in subfolders, e.g. configuring path: '{{year}}/{{slug}}' will save the content under posts/2019/post-title.md.
Media and Public Folder
By default Static CMS stores media files for all collections under a global media_folder directory as specified in the configuration.
When using the global media_folder directory any entry field that points to a media file will use the absolute path to the published file as designated by the public_folder configuration.
For example configuring:
And saving an entry with an image named image.png will result in the image being saved under static/media/image.png and relevant entry fields populated with the value of /media/image.png.
Some static site generators (e.g. Gatsby) work best when using relative image paths.
This can now be achieved using a per collection media_folder configuration which specifies a relative media folder for the collection.
For example, the following configuration will result in media files being saved in the same directory as the entry, and the image field being populated with the relative path to the image.
More specifically, saving an entry with a title of example post with an image named image.png will result in a directory structure of:
And for the image field being populated with a value of image.png.
Note: When specifying a path on a folder collection, media_folder defaults to an empty string.
Available Template Tags
Supports all of the slug templates and:
{{dirname}} The path to the file's parent directory, relative to the collection's folder.
Nested Collections
Nested collections allow a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory.
Example configuration:
Nested collections expect the following directory structure:
File Collections
A files collection contains one or more uniquely configured files. Unlike items in folder collections, which repeat the same configuration over all files in the folder, each item in a files collection has an explicitly set path, filename, and configuration. This can be useful for unique files with a custom set of fields, like a settings file or a custom landing page with a unique content structure.
When configuring a files collection, configure each file in the collection separately, and list them under the files field of the collection. Each file has its own list of fields and a unique filepath specified in the file field (relative to the base of the repo).
Note: Files listed in a file collection must already exist in the hosted repository branch set in your Static CMS backend configuration. Files must also have a valid value for the file type. For example, an empty file works as valid YAML, but a JSON file must have a non-empty value to be valid, such as an empty object.

Backend

Publish Mode

Media and Public Folders

Site URL

Display URL

Custom Logo

Locale

Search

Slug Type

Disable Local Backup

YAML 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:
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
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 are 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
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
Publish Mode
By default, all entries created or edited in Static 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 on a dashboard according to their status, and they can be further reviewed and edited before going live.
See Editorial Workflow for more information.
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
The media_folder option specifies the folder path where uploaded files should be saved, relative to the base of the repo.
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.
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
The media_library settings allows customization of the media library.
Options
Example
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:
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:
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:
Locale
Static CMS locale. Defaults to en.
Example
In your config:
When a translation for the selected locale is missing the English one will be used.
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:
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.\
slug accepts multiple options:
encoding
clean_accents: Set to true to remove diacritics from slug characters before sanitizing. This is often helpful when using ascii encoding.
Example
Collections
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.
YAML Options
The YAML format parsing and stringifing can be customized via the yaml setting. Available options can be found in the yaml docs,
Example

By default, all entries created or edited in Static 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. The unpublished entries will be arranged on a dashboard, in Static CMS, according to their status (Draft, Ready for Review, Ready To Publish). This allows for quick access to unpublished entries, allowing them to be reviewed and edited before going live.
You can enable the Editorial Workflow with the following line in your config.yml file:
From a technical perspective, the workflow translates editor UI actions into common Git commands:

Git Gateway with Netlify

Reconnect after Changing Repository Permissions

Git Gateway without Netlify

Name: git-gateway
Git Gateway with Netlify
The Netlify Identity service can handle the authentication and provides a simple interface for user management. The Static CMS featured templates are working examples of this backend.
To use it in your own project stored on GitHub or GitLab, follow these steps:
Reconnect after Changing Repository Permissions
If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the Netlify Git Gateway docs.
Git Gateway without Netlify
You can use Git Gateway without Netlify by setting up your own Git Gateway server and connecting it with your own instance of GoTrue (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).
To configure in Static CMS, use the same backend settings in your Static CMS config file as described in Step 2 of the Git Gateway with Netlify Identity instructions above.

Widget Options

Example

Name: boolean
The boolean widget translates a toggle switch input to a true or false value.
Widget Options
For common options, see Common widget options.
Example

Name: code
The code widget provides a code editor (powered by Codemirror) with optional syntax awareness. Can output the raw code value or an object with the selected language and the raw code value.
Widget Options
For common options, see Common widget options.
Example

Name: color
The color widget translates a color picker to a color string.
Widget Options
For common options, see Common widget options.
Examples
Basic
Kitchen Sink

Name: datetime
The datetime widget translates a datetime picker to a datetime string.
Widget Options
For common options, see Common widget options.
Examples
Date Time Picker
Date Picker
Time Picker

Name: file
The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string.
Widget Options
For common options, see Common widget options.
Examples

Name: hidden
Hidden widgets do not display in the UI. In folder collections that allow users to create new items, you will often want to set a default for hidden fields, so they will be set without requiring an input.
Widget Options
For common options, see Common widget options.
Example

Name: image
The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string.
Widget Options
For common options, see Common widget options.
Example

Name: keyvalue
The key value widget allows editors to enter an arbitrary number of key/value pairs.
Widget Options
For common options, see Common widget options.
Example

Name: list
The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. You can choose any widget as a child of a list widget—even other lists.
Widget Options
For common options, see Common widget options.
Examples
Basic
Allow Additions
Default Value
Start Collapsed
Min and Max
Add To Top
Delimiter Separated List
Singleton List (List of Strings)
Typed List

Name: map
The map widget allows you to edit spatial data using an interactive map. Spatial data for a single piece of geometry saves as a GeoJSON string in WGS84 projection.
Widget Options
For common options, see Common widget options.
Example

Toolbar Customization

Shortcodes

Name: markdown
The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button.
Widget Options
For common options, see Common widget options.
Example
This would render as:
Toolbar Customization
Options
All toolbars can be customized with a list consisting of buttons and dropdown menus.
Buttons
Buttons can be configured simply with their name. The following options are available:
blockquote
Menus
The following options are available for menus:
Menu Groups
The following options are available for menu groups:
Default Values
Below are the default values for the various toolbars:
Main Toolbar
Empty Toolbar
Selection Toolbar
Empty Table Cell Toolbar
Table Selection Toolbar
Shortcodes
Shortcodes can be added to customize the Markdown editor via registerShortcode.
Usage
Interacting With The Media Library
If you want to use the media library in your shortcode you will need to use the useMediaInsert and useMediaAsset hooks.
useMediaInsert - Takes the current url to your media, details about your field and a callback method for when new media is uploaded. If you want to select folders instead of files, set the forFoldervariable in options.

Getting started with contributing

The basics of the Static CMS docs

Style guidelines

Filing issues

Improve existing content

Other places to get involved

We are hoping that Static CMS will do for the Jamstack what WordPress did for dynamic sites back in the day. We know we cannot do that without building a thriving community of contributors and users, and we would love to have you join us.
Getting started with contributing
The basics of the Static CMS docs
The GitHub website allows you to submit issues, work with files, search for content, and browse changes that have been submitted in the past and those that are being submitted now (aka Pull Requests).
Style guidelines
Filing issues
When filing an issue, it is important to remember the Code of Conduct.
Improve existing content
Other places to get involved

Git Large File Storage (LFS)

Name: github
For repositories stored on GitHub, the github backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.
Authentication
Because Github requires a server for authentication, Netlify facilitates basic GitHub authentication.
To enable basic GitHub authentication:
Git Large File Storage (LFS)
Please note that the GitHub backend does not support git-lfs.

Requirements

Image transformations

If you have a Netlify site with Large Media enabled, Static CMS will handle Large Media asset files seamlessly, in the same way as files stored directly in the repository.
Requirements
To use Netlify Large Media with Static CMS, you will need to do the following:
Configure Static CMS to use the Git Gateway backend with Netlify Identity.
When these are complete, you can use Static CMS as normal, and the configured asset files will automatically be handled by Netlify Large Media.
Image transformations
All JPEG, PNG, and GIF files that are handled with Netlify Large Media also have access to Netlify's on-demand image transformation service. This service allows you to request an image to match the dimensions you specify in a query parameter added to the image URL.
You can learn more about this feature in Netlify's image transformation docs.
Media Gallery Thumbnails
In repositories enabled with Netlify Large Media, Static CMS will use the image transformation query parameters to load thumbnail-sized images for the media gallery view. This makes images in the media gallery load significantly faster.
Note: When using this option all tracked file types have to be imported into Large Media. For example if you track *.jpg but still have jpg-files that are not imported into Large Media the backend will throw an error. Check the netlify docs on how to add previously committed files to Large Media.

Enabling Open Authoring

Usage

Alternative for external contributors with Git Gateway

Linking to specific entries in the CMS

When using the GitHub backend, you can use Static CMS to accept contributions from GitHub users without giving them access to your repository. When they make changes in the CMS, the CMS forks your repository for them behind the scenes, and all the changes are made to the fork. When the contributor is ready to submit their changes, they can set their draft as ready for review in the CMS. This triggers a pull request to your repository, which makes it appear in the Dashboard for maintainers.
At the same time, any contributors who do have write access to the repository can continue to use Static CMS normally.
Requirements
You must use the GitHub backend.
For private GitHub repos the user must have read access on the repo, and you must explicitly set the auth_scope to repo, for example:
Enabling Open Authoring
Usage
When a user logs into Static CMS who does not have write access to your repo, the CMS asks for permission to create a fork of your repo (or uses their existing fork, if they already have one). They are then presented with the normal CMS interface. The published content shown is from the original repo, so it stays up-to-date as changes are made.
On the editorial workflow screen, the normal three columns are replaced by two columns instead — Draft and Ready to Review.
When they make changes to content in the CMS, the changes are made to a branch on their fork. In the editorial workflow screen, they see only their own pending changes. Once they are ready to submit their changes, they can move the card into the "Ready To Review" column to create a pull request. When the entry is published (by a repository maintainer via their Static CMS UI), Static CMS deletes the branch, closes the PR and removes the card from the user's editorial workflow screen. Open Authoring users cannot publish entries through the CMS.
Users who do have write access to the original repository continue to use the CMS normally.
Alternative for external contributors with Git Gateway
Users do not need to know about GitHub or create a GitHub account. Instead, they use Netlify Identity accounts that are created on your site and managed by you.
Linking to specific entries in the CMS
Open authoring often includes some sort of "Edit this page" link on the live site. Static CMS supports this via the edit path:
For the entry named "general" in the "settings" file collection
For blog post "test.md" in the "posts" folder collection
collectionName: the name of the collection as entered in the CMS config.

Preview Templates

Static CMS provides first class support for Typescript when using the Bundling option.
Configuration
When using Typescript it is recommended to store your CMS configuration in a typescript file instead of a yaml file to take full advantage of the typings available.
Custom Widgets
When providing your own widgets, you can extend the Config type with your custom widget types to provide proper typing in your config. All custom widget types should extend the BaseField interface.
Widgets
When providing types for custom widgets you need to know the datatype your widget works with and the definition of its Field. The examples below assumes the field interface for the widget is in the config.ts file in the parent directory.
Control Component
Control widgets take the WidgetControlProps interface as their props.
Preview Component
Control widgets take the WidgetPreviewProps interface as their props.
Preview Templates
When providing types for custom preview templates you need to know the datatype of your collection (or file) that the template is represents. Preview templates take the TemplatePreviewProps interface as their props.

Name: number
The number widget uses an HTML number input, saving the value as a string, integer, or floating point number.
Widget Options
For common options, see Common widget options.
Example

Name: object
The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget, even other object widgets.
Widget Options
For common options, see Common widget options.
Example

Name: relation
The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you are referencing, and the list automatically updates with matched entries based on what you have typed.
Widget Options
For common options, see Common widget options.
Examples
Referencing A Folder Collection
The generated UI input will search the authors collection by name and twitterHandle, and display each author's handle and follower count. On selection, the author's name is saved for the field.
String Template
The generated UI input will search the authors collection by name, and display each author's handle and follower count. On selection, the author entry slug is saved for the field.
Referencing A File Collection List Field
The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id is saved for the field.

Name: select
The select widget allows you to pick a string value from a dropdown menu.
Widget Options
For common options, see Common widget options.
Examples
Options As Strings
Selecting the center option, will save the value as:
Options As Numbers
Selecting the 2 option, will save the value as:
Options As Objects
Selecting the Chicago option, will save the value as:
Multiple
Min and Max

Name: string
The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget.
Widget Options
For common options, see Common widget options.
Example

Name: text
The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget.
Widget Options
For common options, see Common widget options.
Example

Name: uuid
The uuid widget generates a unique id (uuid) and saves it as a string.
Widget Options
For common options, see Common widget options.
Example

Name: bitbucket
For repositories stored on Bitbucket, the bitbucket backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work.
Authentication
To enable Bitbucket authentication it:

Register Theme

Extend Built-in Themes

Set Default Theme

Hide Built-in themes

useTheme Hook

Theme

Static CMS comes with two default themes (light and dark), and you can add your own custom themes as well.
Static CMS exposes a window.CMS global object that you can use to register custom themes via registerTheme. The same object is also the default export if you import Static CMS as an npm module.
Register Theme
Register a custom theme.
Extend Built-in Themes
Extend either the light or dark themes.
Set Default Theme
By default light is the main theme (or dark if the user's system is set to dark mode). default_theme allows you to change that.
Hide Built-in themes
By default both a light and dark them are available. However, if you provide at least one custom theme, include_built_in_themes allows you to disable the built-in themes.
If default_theme is not provided, then the first custom theme is used (when include_built_in_themes is false).
useTheme Hook
The useTheme hook can be utilized in customize widgets and previews to utilize values from the theme.
Example Preview Card
Theme
The react component that renders the control. It receives the following props:
Common Colors
common allows you to change the common colors.
Text Colors
text allows you to change the text colors.
Background Colors
background allows you to change the background colors.
Scrollbar Colors
scrollbar allows you to change the scrollbar colors.
Theme Color
primary, error, warning, info and success are theme colors and share the same options.
Codemirror
codemirror allows you to change the theme settings for Codemirror instances (used by the code and markdown widgets).

Static CMS can provide a side by side interface for authoring content in multiple languages.
Top level configuration
Collection level configuration
When using a file collection, you must also enable i18n for each individual file:
Field level configuration
Example configuration:
collections:
Limitations

Documentation Formatting Standards

Inline code formatting

Code snippet formatting

Content best practices

Patterns to avoid

Documentation Formatting Standards
Use angle brackets for placeholders
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
where <package-name> is the name of a package.
Use bold for user interface elements
Use italics to define or introduce new terms
Use code style for filenames, directories, and paths
Use the international standard for punctuation inside quotes
Inline code formatting
Use code style for inline code and commands
For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick ().
Use code style for object field names
Use normal style for string and integer field values
For field values of type string or integer, use normal style without quotation marks.
Code snippet formatting
Don't include the command prompt
Content best practices
This section contains suggested best practices for clear, concise, and consistent content.
Use present tense
Exception: Use future or past tense if it is required to convey the correct meaning.
Use active voice
Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
Address the reader as "you"
Avoid Latin phrases
Prefer English terms over Latin abbreviations.
Exception: Use "etc." for et cetera.
Patterns to avoid
Avoid using "we"
Using "we" in a sentence can be confusing, because the reader might not know whether they are part of the "we" you are describing.
Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
Avoid statements about the future
Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
Avoid statements that will soon be out of date
Avoid words like "currently" and "new." A feature that is new today will not be new in a few months.

Register Widget

Advanced field validation

Interacting With The Media Library

Static CMS exposes a window.CMS global object that you can use to register custom widgets via registerWidget. The same object is also the default export if you import Static CMS as an npm module.
React Components Inline
The registerWidget requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate with this build process.
However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Static CMS exposes some constructs globally to allow you to create components inline: h (alias for React.createElement) as well some basic hooks (useState, useMemo, useEffect, useCallback).
Register Widget
Register a custom widget.
Params
Control Component
The react component that renders the control. It receives the following props:
Query
query allows you to search the entries of a given collection. It accepts the following props:
Preview Component
The react component that renders the preview. It receives the following props:
Options
Register widget takes an optional object of options. These options include:
Example
admin/config.yml (or admin/config.js)
Advanced field validation
All widget fields, including those for built-in widgets, include basic validation capability using the required and pattern options.
With custom widgets, the widget can also optionally pass in a validator method to perform custom validations, in addition to presence and pattern. The validator function will be automatically called, and it can return either a boolean value, an object with a type and error message or a promise.
Examples
No Errors
Has Error
Error With Type
Error With Type and Message
Promise
You can also return a promise from validator. The promise can return boolean value, an object with a type and error message or a promise.
Interacting With The Media Library
If you want to use the media library in your custom widget you will need to use the useMediaInsert and useMediaAsset hooks.
useMediaInsert - Takes the current url to your media, details about your field (including a unique ID) and a callback method for when new media is uploaded. If you want to select folders instead of files, set the forFolder variable in options.

Name: gitlab
For repositories stored on GitLab, the gitlab backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work.
Note: GitLab default branch is protected by default, thus typically requires maintainer permissions in order for users to have push access.
Authentication
With GitLab's PKCE authorization, users can authenticate with GitLab directly from the client. To do this:
Example
Self-Hosted GitLab Instance
You can also use PKCE Authorization with a self-hosted GitLab instance. This requires adding api_root, base_url, and auth_endpoint fields:
Example
Git Large File Storage (LFS)
The GitLab backend does support git-lfs.

Name: gitea
For repositories stored on Gitea, the gitea backend allows CMS users to log in directly with their Gitea account. Note that all users must have push access to your content repository for this to work.
Please note that only Gitea v1.20 and upwards is supported due to API limitations in previous versions.
Authentication
With Gitea's PKCE authorization, users can authenticate with Gitea directly from the client. To do this:
Git Large File Storage (LFS)
Please note that the Gitea backend does not support git-lfs.

Editor Preview

Editor Preview Styles

Collection Card Preview

Collection Field Preview

Static CMS exposes a window.CMS global object that you can use to register custom previews for an entire collection (or file within a file collection) via registerPreviewTemplate (editor view) and registerPreviewCard / registerFieldPreview (collection view).
React Components Inline
registerPreviewTemplate, registerPreviewCard and registerFieldPreview require you to provide a React component. If you have a build process in place for your project, it is possible to integrate with this build process.
However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Static CMS exposes some constructs globally to allow you to create components inline: h (alias for React.createElement) as well some basic hooks (useState, useMemo, useEffect, useCallback).
Editor Preview
registerPreviewTemplate allows you to create a template that overrides the entire editor preview for a given collection.
Params
The following parameters will be passed to your react_component during render:
Example
Lists and Objects
The API for accessing the individual fields of list- and object-type entries is similar to the API for accessing fields in standard entries, but there are a few key differences. Access to these nested fields is facilitated through the widgetsFor function, which is passed to the preview template component during render.
List Template Example
For list fields, the widgetFor function returns an array of objects that you can map over in your template. If your field is a list of authors containing two entries, with fields name and description, the return value of widgetsFor would look like this:
Object Example
Object fields are simpler than lists - instead of widgetsFor returning an array of objects, it returns a single object. Accessing the shape of that object is the same as the shape of objects returned for list fields:
Editor Preview Styles
Register a custom stylesheet to use on the preview pane.
Raw Styles
If you want to provide a raw CSS string instead of a url, you can pass { raw: true } as the second parameter.
Collection Card Preview
registerPreviewCard allows you to create a card template that overrides the cards displayed in the collection view.
Params
The following parameters will be passed to your react_component during render:
Example
Grid View
Collection Field Preview
registerFieldPreview allows you to create a custom preview for a specific field in the table view for collections.
Params
The following parameters will be passed to your component during render:
Example
Table View

The local backend allows you to use Static CMS with a local git repository, instead of working with a live repo, regardless of backend provider. It will read and write file from your local file system inside your local git repository. You will still need to manually commit and push any files you have changed or added after completing the edits.
Configuration
Example
backend:
backend: {
Usage
Note: @staticcms/proxy-server runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development.
Configure Proxy Server Port
local_backend:

Params

Static CMS exposes a window.CMS global object that you can use to register external links or links custom pages, via registerAdditionalLink. The links are displayed at the bottom of the navigation menu in the order they are registered.
React Components Inline
The registerAdditionalLink requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate with this build process.
However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Static CMS exposes some constructs globally to allow you to create components inline: h (alias for React.createElement) as well some basic hooks (useState, useMemo, useEffect, useCallback).
Params
registerAdditionalLink takes an AdditionalLink object with the following properties:
Options
Available options for each additional link are:
Examples
External Links
Custom Page

Name: gitlab
You can use the test-repo backend to try out Static CMS without connecting to a Git repo. With this backend, you can write and publish content normally, but any changes will disappear when you reload the page. This backend powers the Static CMS demo site.
Note: The test-repo backend cannot access your local file system, nor does it connect to a Git repo, thus you will not see any existing files while using it.
To enable this backend, set your backend name to test-repo in your Static CMS config file.
Example

Static CMS exposes a window.CMS global object that you can use to register custom icons via registerIcon. The same object is also the default export if you import Static CMS as an npm module.
Custom icons can be used with Collections or Custom Links & Pages
Params
Example
This example uses Font Awesome to supply the icon.
Usage
Collection
Additional Links
See Additional Links for details.

Package Manager

The update procedure for your CMS depends upon the method you used to install Static CMS.
Package Manager
If you are using a package manager like Yarn or NPM, use their standard procedure to update. This is how both the Hugo and Gatsby starters are set up.
CDN
If you are using Static CMS through a CDN like Unpkg, then that depends on the version tag you are using. You can find the version tag in the /admin/index.html file of your site.
If you use ~4.0.0, Static CMS will do only patch updates automatically.

Installing

Date Template Transformation

List / Object Filter Rules

i18n Config

Type Changes (TypeScript)

Static CMS v4 introduces:
In this guide, we will walk you through the steps for upgrading to Static CMS v4.
Please report any issues you encounter while upgrading to Static CMS v4.
Installing
To install the latest version of Static CMS:
Or if you are using yarn:
If you are using a CDN to load Static CMS, simply change your URLs:
View Filters
The view_filters configuration option has been slightly changed, as we now allow a default filter option. Also each filter now requires a unique name.
Old setup
New setup
View Groups
The view_groups configuration option has been slightly changed, as we now allow a default grouping option. Also each group now requires a unique name.
Old setup
New setup
Theme
The theme prop has been removed from:
Custom widget control components and preview components
The new useTheme hook should be instead to get the colors of the current theme.
Date Template Transformation
The date template transformation now uses date-fns tokens instead of momentjs.
List / Object Filter Rules
Previously, when using Filtered Folder Collections, specifying a list field, Static CMS would search the values of the list to find a match. Now the default behavior is to match the JSON formatted version of the list's value. To match values inside the list, simply add .* to the end of your filter field.
Object fields are also now matched against the JSON formatted version of their values.
Old setup
New setup
i18n Config
For i18n, the setting defaultLocale has been renamed to default_locale.
Type Changes (TypeScript)
The StringOrTextField type has been split into StringField and TextField.

Mounted Event

Login Event

Logout Event

You can execute a function when a specific event occurs within Static CMSD.
Supported events are:
Mounted Event
The mounted event handler fires once Static CMS is fully loaded.
Login Event
The login event handler fires when a user logs into Static CMS.
Logout Event
The logout event handler fires when a user logs out of Static CMS.
Change Event
The change event handler fires when a user changes the value of a field in the editor. Event listeners for change can optionally provide collection, file and field names. They can also be used to modify the entry data.
Pre Save Event
The preSave event handler fires before the changes have been saved to your git backend, and can be used to modify the entry data.
Post Save Event
The postSave event handler fires after the changes have been saved to your git backend.
Pre Publish Event
The prePublish event handler fires before the entry is "published", before the PR is merged into default branch.
Post Publish Event
The postPublish event handler fires after the entry is "published", after the PR is merged into default branch.

Name	Type	Default	Description
name	'git-gateway' \| 'github' \| 'gitlab' \| 'bitbucket' \| 'gitea' \|'test-repo' \| 'proxy'		The backend git provider
repo	string		Required for `github`, `gitlab`, `gitea` and `bitbucket` backends. Ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`
branch	string	`main`	Optional. The branch where published content is stored. All CMS commits and PRs are made to this branch
api_root	string	GitHub `https://api.github.com` GitLab `https://gitlab.com/api/v4` Bitbucket `https://api.bitbucket.org/2.0` Gitea `https://try.gitea.io/api/v1`	Optional. The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab
site_domain	string	`location.hostname` On `localhost` `cms.netlify.com`	Optional. Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly
base_url	string	GitHub or Bitbucket `https://api.netlify.com` GitLab `https://gitlab.com` Gitea `https://try.gitea.io`	Optional. OAuth client hostname (just the base domain, no path). Required when using an external OAuth server or self-hosted GitLab/Gitea
auth_endpoint	string	GitHub or Bitbucket `auth` GitLab `oauth/authorize`	Optional. Path to append to `base_url` for authentication requests.
cms_label_prefix	string	`cms/`	Pull (or Merge) Requests label prefix when using editorial workflow. Optional.