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

Local Backend

Test Backend

Backends

Collections Configuration

Collection Types

Collections

Boolean

Code

Color

DateTime

File

Hidden

Image

List

Markdown

Number

Object

Relation

Select

String

Text

Widgets

Cloudinary

Netlify Large Media

Uploadcare

Media

Gatsby

Hugo

Jekyll

NextJS

Nuxt

Middleman

Gridsome

Docusaurus

Guides

Platform Guides

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

Install Static CMS

Set up a backend

Configure Static CMS using a configuration file

Render the content provided by Static CMS as web pages

Local development

The process for adding Static CMS to a static site can be divided into four main steps:
Install Static CMS
This is a single page app available at the /admin route of your website.
Set up a backend
This serves two purpose: Secure access to your website's Static CMS and allows it to read and update content files in your repo. More information about configuring the backend can be found here.
Configure Static CMS using a configuration file
For starters, you can get by with a basic configuration that includes required information like Git provider, branch and folders to save files to.
Once you've gotten the hang of it, you can use the file to build whatever collections and content modeling you want. Check out the this section for full details about all available configuration options.
Render the content provided by Static CMS as web pages
Static CMS manages your content, and provides admin features, but it doesn't deliver content. It only makes your content available through an API.
It is up to developers to determine how to build the raw content into something useful and delightful on the frontend.
To learn how to query raw content managed by Static CMS and reformat them for delivery to end users, please refer the dedicated section for your site generator in the Table of Content.
Local development
If you are experimenting with Static CMS or testing things out, you can connect it to a local Git repository instead of a live one. Learn how to do it here.

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 import it (assuming your project has tooling for imports):
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.
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). Alternatively, you can use a yaml file (admin/config.yml) instead of a javascript file.
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.

Create a new Gatsby site

Get to know Gatsby

Add Static CMS to your site

Start publishing

This guide will help you get started using Static CMS and Gatsby.
To get up and running with Gatsby, you'll need to have Node.js installed on your computer. Note: Gatsby's minimum supported Node.js version is Node 8.
Create a new Gatsby site
Let's create a new site using the default Gatsby Starter Blog. Run the following commands in the terminal, in the folder where you'd like to create the blog:
Get to know Gatsby
In your favorite code editor, open up the code generated for your "Gatsby Starter Blog" site, and take a look at the content directory.
You will see that there are multiple Markdown files that represent blog posts. Open one .md file and you will see something like this:
We can see above that each blog post has a title, a date, a description and a body. Now, let's recreate this using Static CMS.
Add Static CMS to your site
First let's install some dependencies. We'll need @staticcms/core and gatsby-plugin-netlify-cms. Run the following command in the terminal at the root of your site:
Configuration
For the purpose of this guide we will deploy to Netlify from a GitHub repository which requires the minimum configuration.
Create a config.yml file in the directory structure you see below:
In your config.yml file paste the following configuration:
media_folder: static/img
collections:
Note: The above configuration allows assets to be stored relative to their content. Therefore posts would be stored in the format below as it is in gatsby-starter-blog.
Finally, add the plugin to your gatsby-config.js.
Push to GitHub
It's now time to commit your changes and push to GitHub. The Gatsby starter initializes Git automatically for you, so you only need to do:
Add your repo to Netlify
Go to Netlify and select 'New Site from Git'. Select GitHub and the repository you just pushed to. Click Configure Netlify on GitHub and give access to your repository. Finish the setup by clicking Deploy Site. Netlify will begin reading your repository and starting building your project.
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:
Start publishing
It's time to create your first blog post. Login to your site's /admin/ page and create a new post by clicking New Blog. Add a title, a date and some text. When you click Publish, a new commit will be created in your GitHub repo with this format Create Blog "year-month-date-title".
Then Netlify will detect that there was a commit in your repo, and will start rebuilding your project. When your project is deployed you'll be able to see the post you created.
Cleanup
It is now safe to remove the default Gatsby blog posts.

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.

Getting started with Hugo

Getting Started With Static CMS

Using Static CMS content in Hugo

This guide will walk you through how to integrate Static CMS with Hugo. This is a good place to start if you want to learn from the ground up how these two tools work together. If you want to get up-and-running quicker, you can use one of the pre-existing and amazing starter templates!
Getting started with Hugo
Installation
To get started with Hugo, you should first install the command line tool. If you've already got it installed, you can skip this step. On MacOS and Linux you can do this with:
To test that it's successfully installed, you can try this command, to get a list of Hugo's options:
Creating a new site
Create a new Hugo project and start it up using the following commands.
You won't actually see anything, just yet, and that's because you don't have any template files. That's easily resolved. In the layouts/ directory, create a file index.html and put a basic HTML structure in there:
You'll also add some files to the content/ and data/ directories to make sure git tracks them.
This is as basic as you can get with a Hugo project. There's just enough here now for us to install Static CMS.
Getting Started With Static CMS
Add the Static CMS files to Hugo
In Hugo, static files that don't need to be processed by the build commands live in the static/ directory. You'll install the Static CMS admin and config files there. Create a directory admin/ and within it, create two files index.html and config.yml. In the index.html, add the following content:
In the config.yml file, you can add this basic configuration — you can customize as you see fit, this sample file is just to get you started.
Note: You won't be able to access the CMS just yet — you still need to deploy the project with Netlify and authenticate with Netlify Identity. You'll handle this in the next few steps of this guide.
Pushing to GitHub
It's now time to commit your changes and push to GitHub. You can run the following commands to initialize a git repository and push the changes so far.
Deploying With Netlify
Now you can go ahead and deploy to Netlify. Go to your Netlify dashboard and click New site from Git. Select the repo you just created. Under Basic build settings, you can set the build command to hugo and the publish directory to public. Click Deploy site to get the process going.
Authenticating with Netlify Identity
Add the Netlify Identity Widget
You've already added the Netlify Identity widget to our admin/index.html. The next thing to do is add the Netlify Identity widget to our site's index page. In layouts/index.html, we can add the following to the <head> tag on the page:
Once you've added this, make sure to push your changes to GitHub!
Enable Identity & Git Gateway in Netlify
Back in your Netlify dashboard:
Accessing the CMS
Once you've reached this point, you should be able to access the CMS in your browser at http://localhost:1313/admin. You'll be prompted to add the URL of your Netlify site. Once you've added that URL, you can log in with an Identity account or with one of the External Providers you enabled in step 3 above. For the sake of this tutorial, you can create a blog post in the CMS, and publish it! Once you git pull in your project, the blog post will show up in the project at content/blog/<slugified-blog-post-title>.md.
And that's it! From this point on, it's just a matter of following the Hugo documentation for outputting the content from your content/ directory into templates! For more information on configuring Static CMS, feel free to check out the Static CMS configuration options documentation.
Using Static CMS content in Hugo
Creating a list of posts
In your layouts/index.html file, you'll create an unordered list element and use a Hugo range to output all posts. Inside that range, you can add a list item element with each post title and a link to the post inside it.
Note: To learn more about Hugo's range function, check out the Hugo documentation.
That link won't work just right just yet. You'll need to make a single page layout for blog posts, so Hugo can create a page for the .RelPermalink to link to.
Creating a single page post layout
Create a file layouts/blog/single.html, and put the following content in there:
You can see this basic template includes all the fields you've specified in your Static CMS config.yml file. You can access any custom front-matter fields with .Params.<field-name>!

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:

Setup

Add Static CMS

CMS Configuration

This section will help you integrate Static CMS with a new or existing Jekyll project.
If you're starting a new project, the fastest route to publishing on a Jekyll website with Static CMS is to deploy a template on Netlify.
Setup
This guide will use the blog you get if you follow the really excellent official Jekyll step by step tutorial as a starting point. If you're new to Jekyll - I recommended you start by following the tutorial so you know your way around your new blog. Otherwise you can clone this repo and checkout the without-cms branch.
Add Static CMS
Add admin/index.html
Create a file admin/index.html in the root of your repo - it should look like this:
Add admin/config.yml
Create a file admin/config.yml in the root of your repo - it should look like this:
backend:
Enable authentication for CMS users
Static CMS stores content in your online Git repository. Therefore, to make content changes, users need to authenticate with the corresponding Git provider to prove that they have read and write access to that content.
Follow the directions in the Introduction section to enable Netlify Identity and Git Gateway services for the backend, then add the Identity widget to render a login portal on the frontend.
CMS Configuration
Blog Collection
We'll start by updating the blog collection. Blogging is baked into Jekyll, and the _posts/ directory uses some special conventions we'll need to keep in mind as we configure Static CMS. Copy and paste the following into your config.yml.
A few things to note.
* We set the slug to '{{year}}-{{month}}-{{day}}-{{slug}}' because Jekyll requires this format for blog posts. year, month, and day will be extracted from the date field, and slug will be generated from the title field.
Author Collection
In addition to _posts, the Jekyll tutorial blog includes a collection of authors in the _authors directory. Before we can configure Static CMS to work with the authors collection, we'll need to make a couple tweaks to our Jekyll blog. Here's the front matter for one of the authors.
name has special meaning as a unique identifier in Static CMS, but as set up now our Jekyll blog is using short_name as the unique identifier for authors. For each author, update the frontmatter like so.
then update _layouts/author.html, _layouts/post.html and staff.html accordingly.
-- layout: default ---
{{ content }}
-- layout: default ---
{{ content }}
-- layout: default ---
Next, copy and paste the following into the collections array in config.yml below the blog collection.
Now that we have the authors collection configured, we can add an author field to the blog collection. We'll use the relation widget to define the relationship between blog posts and authors.
With that configuration added, you should be able to select the author for a post from a dropdown.
About Page
Our Jekyll blog includes an About page. It would nice to be able to edit that page just like we can edit our blog and author pages. Static CMS provides file collections to solve this problem.
Copy and paste the following into the collections array in config.yml
Navigation
The last aspect of our Jekyll blog we might want to bring under the control of Static CMS is our Navigation menu. Our Jekyll tutorial blog has a file _data/navigation.yml that defines the links rendered by _includes/navigation.html. It looks like this.
To make this file editable with Static CMS, we'll need to make one minor tweak. The issue is this file contains a yaml array at the top level, but Static CMS is designed to work with yaml objects. Update _data/navigation.yml so it looks like so.
You'll need to update _includes/navigation.html accordingly. {% for item in site.data.navigation %} should be changed to {% for item in site.data.navigation.items %}. When you're done, the nav html should look like this.
Finally, add the following to the collections array in config.yml
Now you can add, rename, and rearrange the navigation items on your blog.

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

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/index.html
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.

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

Creating a new project

Adding Static CMS

Publishing to GitHub and Netlify

This guide will help you get started using Static CMS with NextJS.
Creating a new project
Let's repeat some of the basics of setting up a simple NextJS project (check out nextjs.org/learn for a more detailed version).
Initialize a new project
Install required dependencies
Install webpack loader for Markdown (Use version 3+)
If using NextJS v11.0.0 or above, @babel/core and @babel/preset-react has to be installed as dependencies of frontmatter-markdown-loader
Create folder for pages (default for NextJS), and add a index file
Create a folder for content, and a markdown file:
Create a folder for static assets
Next, we need to add some modifications to our package.json file to make it easier to run and deploy our new site:
There is a lot of different ways to create and display Markdown content, but to make this as easy as possible we'll be using a webpack-loader that enables us to load markdown files directly in our React components (frontmatter-markdown-loader).
Add the following content to your content/home.md file:
This page is built with NextJS, and content is managed in Static CMS
Next, we need to tell webpack how to load Markdown files. Create a new next.config.js file at the root of your project with the following content:
Almost there! The last thing we need to do is to add some content to our pages/index.js file. With a little help of our webpack loader, we can now easily import Markdown files:
Great! We now have a page that displays content from our Markdown file. Go ahead and start your development server to test if everything is working:
Adding Static CMS
There are many different ways to add Static CMS to your project. The easiest is probably just to embed it from a CDN, and that's exactly what we're gonna do. To avoid making this guide too complicated, we're just going to add Netlify into a subfolder inside the /public directory (which is just served as static files by Next):
Create index.html and config.yml file
Paste HTML for Static CMS into your public/admin/index.html file (check out the Add Netlify To Your Site section for more information)
Notice that we also added the identity widget. This allows sign up when the project is hosted at Netlify.
Paste the following configuration into your public/admin/config.yml file:
Awesome! Static CMS should now be available at localhost:3000/admin/index.html. Unfortunately we can't edit our content just yet. First we need to move our code into a git repository, and create a new Netlify site.
Tip: If you want to test changes made to your config.yml file locally, swap out "git-gateway" with "test-repo" and navigate to localhost:3000/admin/index.html to view Static CMS locally (you can't make changes or read actual content from Git this way, but it's great to verify how things will look).
Publishing to GitHub and Netlify
Create a new repository at GitHub (or one of the other supported git services) and follow the instructions on how to push existing files into your new repository.
Now is probably also a good time to add a .gitignore file:
When your project is under version control, go to Netlify and select "New Site from Git". Select GitHub (or whatever service you used in the previous step), and the repository you just pushed to.
Under the final step (Build options, and deploy!), make sure you enter the following:
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:
Celebrate!
Great job - you did it! Open your new page via the new Netlify URL, and navigate to /admin. If you did everything correct in the previous step, you should now be able to sign up for an account, and log in.
Tip: Signing up with an external provider is the easiest. If you want to sign up by email, you'll have to set up a redirect in your index.js page (which we won't be covering in this guide). For more information, have a look at the Add To Your Site section.
Congratulations - you can finally manage your new list of cats!

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 Example:
Object Example:

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:

Starting With `create-nuxt-app`

Setting Up Static CMS

This guide will walk you through how to integrate Static CMS with Nuxt.
Starting With create-nuxt-app
Follow the instructions on the Nuxt documentation for creating a new project, or run:
Setting Up Static CMS
Add the Static CMS files to Nuxt
In the static/ directory, create a new directory admin/. Inside that directory you'll create two files, your index.html and a config.yml. Per the Static CMS documentation, we'll set the content of static/admin/index.html to the following:
For your static/admin/config.yml file, you can put in a basic starter config:
media_folder: static/img
collections:
You can build whatever collections and content modeling you want. The important thing to note is the format: 'frontmatter' value on each collection. This is important for consuming content in Nuxt with the nuxt/content module.
Add the content/ directory to Nuxt
In your root directory, you can create a new directory content/. As you might guess, this is where our content will live. Your filesystem should look about like this, so far:
Pushing to GitHub
It's now time to commit your changes and push to GitHub. create-nuxt-app initializes Git automatically for you, so you only need to do:
Deploying With Netlify
Now you can go ahead and deploy to Netlify. Go to your Netlify dashboard and click New site from Git. Select the repo you just created. Under Basic build settings, you can set the build command to  npm run generate . Set the publish directory to dist. Click Deploy site to get the process going.
Authenticating with Netlify Identity
Add the Netlify Identity Widget
You've already added the Netlify Identity widget to our admin/index.html. The next thing to do is add the Netlify Identity widget to our site's index page. In pages/index.vue, we can add the following to the page <script> tag:
Once you've added this, make sure to push your changes to GitHub!
*More on adding <script> tags to <head> here.*
Enable Identity & Git Gateway in Netlify
Back in your Netlify dashboard:
Accessing the CMS
Using nuxt/content
Static CMS and nuxt/content module click together and complement each other to give you best authoring experience and developer experience respectively.
Adding nuxt/content dependency
Then, add @nuxt/content to the modules section of nuxt.config.js:
By adding nuxt content module you get $content injected into your whole app which you can use to fetch content from your content folder using simple fetch api or nuxt asyncData option.
Example Blog Post List
nuxt/content module gives us $content which we can use to fetch the list of blog posts in content/blog directory.
Example Blog Post
To generate blog posts create a _slug.vue file in the pages folder. By using $content you would get a json which you can use to display. But if you are using markdown to write and store your posts you can use <nuxt-content> module which gives you option to edit content on page in dev mode and many more features.
Generating pages with the generate property
Since Nuxt 2.13+, nuxt export has a crawler feature integrated which will crawl all your links and generate your routes based on those links. Therefore you do not need to do anything in order for your dynamic routes to be crawled. i.e, if you are on version of nuxt above 2.14 add target as static in nuxt.config.js and use nuxt generate to build your static site.
If you are using nuxt version below 2.14 you have to use generate option in nuxt/content module to generate pages
To render your site as a static site, you'll need to create or update the generate property in nuxt.config.js to create dynamic routes and provide their content as a payload. In generate, make your routes entry a function:
To see the generated site, navigate to name-of-your-website.netlify.app/blog

Name	Type	Default	Description
url	string	`http://localhost:8081/api/v1`	URL for proxy server
allowed_hosts	list of hosts	`['localhost', '127.0.0.1']`	Whitelist of allowed hosts when accessing the local site from a host other than 'localhost' or '127.0.0.1'