Overview

Start with a Template

Add to Your Site

CDN Hosting

Bundling

Configuration Options

Typescript

Beta Features

Intro

Getting Started

Updating Your CMS

Netlify CMS Migration Guide

Migration

Migration Guides

Git Gateway

GitHub

Bitbucket

GitLab

Gitea

Local Backend

Test Backend

Backends

Collections Configuration

Collection Types

i18n Support

Collections

Boolean

Code

Color

DateTime

File

Hidden

Image

List

Markdown

Number

Object

Relation

Select

String

Text

Widgets

Cloudinary

Netlify Large Media

Uploadcare

Media

Creating Custom Widgets

Creating Custom Previews

Custom Links & Pages

Adding Custom Icons

Customization

Customizing Static CMS

Contributor Guide

Writing Style Guide

Examples

Contributing

Community

Available Widgets

Common widget options

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

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.

The 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 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 won't 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's 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 the CMS

This tutorial guides you through the steps for adding Static CMS via a public CDN to a site that's 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's the static file location for a few of the most popular static site generators:
If your generator isn't 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's likely you can store your admin folder next to those. (When you've found the location, feel free to add it to these docs by filing a pull request!)
Inside the admin folder, you'll 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's 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 set the src to https://cdn.jsdelivr.net/npm/@staticcms/app@%5E1.0.0/dist/static-cms-app.js
Configuration
Configuration is different for every site, so we'll 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're 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'll get to the details of that in the Authentication section below.) If you leave out the branch declaration, it defaults to main.
Media and Public Folders
Static CMS allows users to upload images directly within the editor. For this to work, the 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're creating a new folder for uploaded media, you'll 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's 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's 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's 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's 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's left is to enable authentication. We're using the Netlify platform here because it's 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's 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 the 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 the 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're 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's 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), and import Static CMS:
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 the 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'll 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're 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'll get to the details of that in the Authentication section below.) If you leave out the branch declaration, it defaults to main.
Media and Public Folders
Static CMS allows users to upload images directly within the editor. For this to work, the 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're creating a new folder for uploaded media, you'll 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's 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's 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's 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's 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's left is to enable authentication. We're using the Netlify platform here because it's 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's 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 the 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 the 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're 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`

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, 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, 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. {{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
This 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
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. {{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.
sortable_fields
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 can't be inferred commit author will be used.
Default Sort
view_filters
An optional list of predefined view filters to show in the UI.
Defaults to an empty list.
view_groups
An optional list of predefined view groups to show in the UI.
Defaults to an empty list.

<img src="https://img.shields.io/badge/-Beta%20Feature-blue" alt="Beta Feature. Use at your own risk" title="Beta Feature. Use at your own risk" />

Creating a Cloudinary Account

Connecting Cloudinary

Static CMS configuration options

Cloudinary configuration options

Image transformations

Inserting Cloudinary URL in page templates

Cloudinary is a digital asset management platform with a broad feature set, including support for responsive image generation and url based image transformation. They also provide a powerful media library UI for managing assets, and tools for organizing your assets into a hierarchy.
The Cloudinary media library integration for Static CMS uses Cloudinary's own media library interface within Static CMS. To get started, you'll need a Cloudinary account and Static CMS 2.3.0 or greater.
Creating a Cloudinary Account
You can sign up for Cloudinary for free. Once you're logged in, you'll need to retrieve your Cloud name and API key from the upper left corner of the Cloudinary console.
Connecting Cloudinary
To use the Cloudinary media library within Static CMS, you'll need to update your Static CMS configuration file with the information from your Cloudinary account:
Note: The user must be logged in to the Cloudinary account connected to the api_key used in your Static CMS configuration.
Security Considerations
Although this setup exposes the cloud_name and api_key publicly via the config endpoint, this information is not sensitive. Any integration of the Cloudinary media library requires this information to be exposed publicly. To use this library or use the restricted Cloudinary API endpoints, the user must have access to the Cloudinary account login details or the api_secret associated with the cloud_name and api_key.
Static CMS configuration options
The following options are specific to the Static CMS integration for Cloudinary:
output_filename_only: (default: false)_\
Cloudinary configuration options
The following options are used to configure the media library. All options are listed in Cloudinary's media library documentation, but only options listed below are available or recommended for the Static CMS integration:
Authentication
cloud_name
Media library behavior
default_transformations \- only the first image transformation is used, be sure to use the SDK Parameter column transformation names from the _transformation reference_
Image transformations
The Cloudinary integration allows images to be transformed in two ways: directly within Static CMS via Cloudinary's Media Library, and separately from the CMS via Cloudinary's dynamic URL's by inserting cloudinary urls.
Transforming Images
If you transform and insert images from within the Cloudinary media library, the transformed image URL will be output by default. This gives the editor complete freedom to make changes to the image output.
Global configuration
Global configuration, which is meant to affect the Cloudinary widget at all times, can be provided
Field configuration
Configuration can also be provided for individual fields that use the media library. The structure
Inserting Cloudinary URL in page templates
If you prefer to provide direction so that images are transformed in a specific way, or dynamically retrieve images based on viewport size, you can do so by providing your own base Cloudinary URL and only storing the asset filenames in your content:
Either globally or for specific fields, configure the Cloudinary extension to only output the asset filename
Global
Field
Provide a dynamic URL in the site template
Your dynamic URL can be formed conditionally to provide any desired transformations - please see Cloudinary's image transformation reference for available transformations.

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 value of a single field. By filtering a folder into different collections, you can manage files with different fields, options, extensions, etc. in the same folder.
The filter option requires two fields:
field: The name of the collection field to filter on.
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.
Folder Collections Path <img src="https://img.shields.io/badge/-Beta%20Feature-blue" alt="Beta Feature. Use at your own risk" title="Beta Feature. Use at your own risk" />
By default the 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 the 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 <img src="https://img.shields.io/badge/-Beta%20Feature-blue" alt="Beta Feature. Use at your own risk" title="Beta Feature. Use at your own risk" />
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

Media and Public Folders

Media Library

Site URL

Display URL

Custom Logo

Locale

Search

Slug Type

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 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
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
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
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:
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:
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:
Custom Logo
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:
Locale
The CMS locale. Defaults to en.
Other languages than English must be registered manually.
Example
In your config:
And in your custom JavaScript code:
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.

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.
Media Library Options
Example

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.
Media Library 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
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

Widget Options

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.
Media Library Options
Example
This would render as:
Shortcodes
Shortcodes can be added to customize the Markdown editor via registerShortcode.
Usage

Getting started with contributing

The basics of the Static CMS docs

Style guidelines

Filing issues

Improve existing content

Other places to get involved

We're hoping that Static CMS will do for the Jamstack what WordPress did for dynamic sites back in the day. We know we can't do that without building a thriving community of contributors and users, and we'd 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

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.

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're referencing, and the list automatically updates with matched entries based on what you've 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: 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:

The 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

Creating an Uploadcare Account

Updating Static CMS Configuration

Configuring the Uploadcare Widget

Field configuration

Integration settings

Uploadcare is a sleek service that allows you to upload files without worrying about maintaining a growing collection — more of an asset store than a library. Just upload when you need to, and the files are hosted on their CDN. They provide image processing controls from simple cropping and rotation to filters and face detection, and a lot more. You can check out Uploadcare's full feature set on their website.
The Uploadcare media library integration for Static CMS allows you to use Uploadcare as your media handler within the CMS itself. It's available by default as of our 2.1.0 release, and works in tandem with the existing file and image widgets, so using it only requires creating an Uploadcare account and updating your Static CMS configuration.
Please make sure that Static CMS is updated to 2.1.0 or greater before proceeding.
Creating an Uploadcare Account
You can sign up for a free Uploadcare account to get started. Once you've signed up, go to your dashboard, select a project, and then select "API keys" from the menu on the left. The public key on the API keys page will be needed in your Static CMS configuration. For more info on getting your API key, visit their walkthrough.
Updating Static CMS Configuration
The next and final step is updating your Static CMS configuration file:
Your config should now include something like this (except with a real API key):
Once you've finished updating your Static CMS configuration, the Uploadcare widget will appear when using the image or file widgets.
Note: You'll need to register the media libraries yourself.
Configuring the Uploadcare Widget
The Uploadcare widget can be configured with settings that are outlined in their docs. The widget itself accepts configuration through global variables and data properties on HTML elements, but with Static CMS you can pass configuration options directly through your config.
Note: all default values described in Uploadcare's documentation also apply in the Static CMS integration, except for previewStep, which is set to true. This was done because the preview step provides helpful information like upload status, and provides access to image editing controls. This option can be disabled through the configuration options below.
Global configuration
Global configuration, which is meant to affect the Uploadcare widget at all times, can be provided as seen above, under the primary media_library property. Settings applied here will affect every instance of the Uploadcare widget.
Field configuration
Configuration can also be provided for individual fields that use the media library. The structure is very similar to the global configuration, except the settings are added to an individual field. For example:
Integration settings
There are several settings that control the behavior of integration with the widget.
* autoFilename (boolean) - specify whether to add a filename to the end of the url. Example: http://ucarecdn.com/:uuid/filename.png

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're part of the "we" you're 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

The 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 registerPreviewTemplate 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).
NOTE: createClass is still provided, allowing for the creation of react class components. However it has now been deprecated and will be removed in v2.0.0.
Register Widget
Register a custom widget.
Params
Control Component
The react component that renders the control. It receives the following props:
Open Media Library
openMediaLibrary allows you to open up the media library popup. It accepts 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.

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.
Authentication
Because Gitea requires a server for authentication and Netlify doesn't support Gitea, a custom OAuth provider needs to be used for basic Gitea authentication.
To enable basic Gitea authentication:
Git Large File Storage (LFS)
Please note that the Gitea backend does not support git-lfs.

Params

The 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.
React Components Inline
The registerPreviewTemplate 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).
NOTE: createClass is still provided, allowing for the creation of react class components. However it has now been deprecated and will be removed in v2.0.0.
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:

Usage

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
when using the default proxy server port
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:

The 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 registerPreviewTemplate 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).
NOTE: createClass is still provided, allowing for the creation of react class components. However it has now been deprecated and will be removed in v2.0.0.
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 can't access your local file system, nor does it connect to a Git repo, thus you won't 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

The 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 the 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 ~1.0.0, the CMS will do only patch updates automatically.

Do you have a great, open source example? Submit a pull request to this page!

How to Migrate

Changes

Deprecated and Removed Features

Static CMS is a fork of Netlify CMS. Many changes have been made, some big, some small. If you are coming from Netlify CMS, here is the list items to watch out for while migrating.
How to Migrate
To migrate, simply replace Netlify CMS with Static CMS, then address the changes below.
CDN
Netlify CMS:
Static CMS:
Bundling
Install Static CMS
Change your imports
Netlify CMS:
Static CMS:
Changes
Deprecated and Removed Features
Beta Features
All beta features from Netlify CMS that were kept, remain in beta and may not fully function in their current state. Please submit an issue for any bugs you find.

Folder Collections Path

Nested Collections

Commit Message Templates

Image widget file size limit

Summary string template transformations

Registering to CMS Events

Static CMS runs new functionality in an open beta format from time to time. That means that this functionality is totally available for use, an it might be ready for primetime, but it could break or change without notice.
Use these features at your own risk.
Folder Collections Path
See Folder Collections Path.
Nested Collections
Seed Nested Collections.
Commit Message Templates
You can customize the templates used by Static CMS to generate commit messages by setting the commit_messages option under backend in your Static CMS config.
Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, {{path}} will include the full path to the file changed.
Setting up your Static CMS config to recreate the default values would look like this:
Static CMS generates the following commit types:
Template tags produce the following output:
{{slug}}: the url-safe filename of the entry changed
Image widget file size limit
You can set a limit to as what the maximum file size of a file is that users can upload directly into a image field.
Example config:
Summary string 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.
Registering to CMS Events
You can execute a function when a specific CMS event occurs.
Example usage:
Supported events are prePublish, postPublish, preSave and postSave. The preSave hook can be used to modify the entry data like so:

Param	Type	Description
id	string	Unique identifier for the link
title	string	Display text for the link
data	string \| React Function Component	`string` - The href for the link `React Function Component` - A react component to render on the route `/page/[id]`
options	object	Optional. See Options