{"componentChunkName":"component---src-templates-doc-page-js","path":"/docs/beta-features/","result":{"data":{"page":{"fields":{"path":"docs/beta-features.md"},"frontmatter":{"title":"Beta Features!","group":"reference"},"html":"

We run new functionality in an open beta format from time to time. That means that this functionality is totally available for use, and we think it might be ready for primetime, but it could break or change without notice.

\n

Use these features at your own risk.

\n

Working with a Local Git Repository

\n

added in netlify-cms@2.10.17 / netlify-cms-app@2.11.14

\n

You can connect Netlify CMS to a local Git repository, instead of working with a live repo.

\n
    \n
  1. Navigate to a local Git repository configured with the CMS.
    2. \n
  2. Run npx netlify-cms-proxy-server from the root directory of the above repository.
    3. \n
  3. Add the top-level property local_backend configuration to your config.yml:
    4. \n
\n
backend:\n  name: git-gateway\n\n# when using the default proxy server port\nlocal_backend: true\n\n# when using a custom proxy server port\nlocal_backend:\n  url: http://localhost:8082/api/v1
\n
    \n
  1. Start your local development server (e.g. run gatsby develop).
    2. \n
\n

Note: netlify-cms-proxy-server runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development.

\n

GitLab and BitBucket Editorial Workflow Support

\n

added in netlify-cms@2.10.6 / netlify-cms-app@2.11.3

\n

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

\n
publish_mode: editorial_workflow
\n

In order to track unpublished entries statuses the GitLab implementation uses merge requests labels and the BitBucket implementation uses pull requests comments.

\n

GitHub GraphQL API

\n

Experimental support for GitHub's GraphQL API is now available for the GitHub backend.

\n

Note: not currently compatible with Git Gateway.

\n

For many queries, GraphQL allows data to be retrieved using less individual API requests compared to a REST API. GitHub's GraphQL API still does not support all mutations necessary to completely replace their REST API, so this feature only calls the new GraphQL API where possible.

\n

You can use the GraphQL API for the GitHub backend by setting backend.use_graphql to true in your CMS config:

\n
backend:\n  name: github\n  repo: owner/repo # replace this with your repo info\n  use_graphql: true
\n

Learn more about the benefits of GraphQL in the GraphQL docs.

\n

Open Authoring

\n

When using the GitHub backend, you can use Netlify CMS to accept contributions from GitHub users without giving them access to your repository. When they make changes in the CMS, the CMS forks your repository for them behind the scenes, and all the changes are made to the fork. When the contributor is ready to submit their changes, they can set their draft as ready for review in the CMS. This triggers a pull request to your repository, which you can merge using the GitHub UI.

\n

At the same time, any contributors who do have write access to the repository can continue to use Netlify CMS normally.

\n

More details and setup instructions can be found on the Open Authoring docs page.

\n

Folder Collections Path

\n

By default the CMS stores folder collection content under the folder specified in the collection setting.

\n

For example configuring folder: posts for a collection will save the content under posts/post-title.md.

\n

You can now specify an additional path template (similar to the slug template) to control the content destination.

\n

This allows saving content in subfolders, e.g. configuring path: '{{year}}/{{slug}}' will save the content under posts/2019/post-title.md.

\n

Folder Collections Media and Public Folder

\n

By default the CMS stores media files for all collections under a global media_folder directory as specified in the configuration.

\n

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.

\n

For example configuring:

\n
media_folder: static/media\npublic_folder: /media
\n

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.

\n

Some static site generators (e.g. Gatsby) work best when using relative image paths.

\n

This can now be achieved using a per collection media_folder configuration which specifies a relative media folder for the collection.

\n

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.

\n
media_folder: static/media\npublic_folder: /media\ncollections:\n  - name: posts\n    label: Posts\n    label_singular: 'Post'\n    folder: content/posts\n    path: '{{slug}}/index'\n    media_folder: ''\n    public_folder: ''\n    fields:\n      - label: Title\n        name: title\n        widget: string\n      - label: 'Cover Image'\n        name: 'image'\n        widget: 'image'
\n

More specifically, saving an entry with a title of example post with an image named image.png will result in a directory structure of:

\n
content\n  posts\n    example-post\n      index.md\n      image.png
\n

And for the image field being populated with a value of image.png.

\n

Note: When specifying a path on a folder collection, media_folder defaults to an empty string.

\n

Available template tags:

\n

Supports all of the slug templates and:

\n\n

List Widget: Variable Types

\n

Before this feature, the list widget allowed a set of fields to be repeated, but every list item had the same set of fields available. With variable types, multiple named sets of fields can be defined, which opens the door to highly flexible content authoring (even page building) in Netlify CMS.

\n

Note: this feature does not yet support default previews and requires registering a preview template in order to show up in the preview pane.

\n

To use variable types in the list widget, update your field configuration as follows:

\n
    \n
  1. Instead of defining your list fields under fields or field, define them under types. Similar to fields, types must be an array of field definition objects.
    2. \n
  2. Each field definition under types must use the object widget (this is the default value for\nwidget).
    3. \n
\n

Additional list widget options

\n\n

Example Configuration

\n

The example configuration below imagines a scenario where the editor can add two \"types\" of content,\neither a \"carousel\" or a \"spotlight\". Each type has a unique name and set of fields.

\n
- label: 'Home Section'\n  name: 'sections'\n  widget: 'list'\n  types:\n    - label: 'Carousel'\n      name: 'carousel'\n      widget: object\n      fields:\n        - { label: Header, name: header, widget: string, default: 'Image Gallery' }\n        - { label: Template, name: template, widget: string, default: 'carousel.html' }\n        - label: Images\n          name: images\n          widget: list\n          field: { label: Image, name: image, widget: image }\n    - label: 'Spotlight'\n      name: 'spotlight'\n      widget: object\n      fields:\n        - { label: Header, name: header, widget: string, default: 'Spotlight' }\n        - { label: Template, name: template, widget: string, default: 'spotlight.html' }\n        - { label: Text, name: text, widget: text, default: 'Hello World' }
\n

Example Output

\n

The output for the list widget will be an array of objects, and each object will have a type key\nwith the name of the type used for the list item. The type key name can be customized via the\ntypeKey property in the list configuration.

\n

If the above example configuration were used to create a carousel, a spotlight, and another\ncarousel, the output could look like this:

\n
title: Home\nsections:\n  - type: carousel\n    header: Image Gallery\n    template: carousel.html\n    images:\n      - images/image01.png\n      - images/image02.png\n      - images/image03.png\n  - type: spotlight\n    header: Spotlight\n    template: spotlight.html\n    text: Hello World\n  - type: carousel\n    header: Image Gallery\n    template: carousel.html\n    images:\n      - images/image04.png\n      - images/image05.png\n      - images/image06.png
\n

Custom Mount Element

\n

Netlify CMS always creates its own DOM element for mounting the application, which means it always takes over the entire page, and is generally inflexible if you're trying to do something creative, like injecting it into a shared context.

\n

You can now provide your own element for Netlify CMS to mount in by setting the target element's ID as nc-root. If Netlify CMS finds an element with this ID during initialization, it will mount within that element instead of creating its own.

\n

Manual Initialization

\n

Netlify CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Netlify CMS before it loads, bypassing need for an actual Netlify CMS config.yml. This is important, for example, when creating tight integrations with static site generators.

\n

Injecting config is technically already possible by setting window.CMS_CONFIG before importing/requiring/running Netlify CMS, but most projects are modular and don't want to use globals, plus window.CMS_CONFIG is an internal, not technically supported, and provides no validation.

\n

Assuming you have the netlify-cms package installed to your project, manual initialization works like this:

\n
// This global flag enables manual initialization.\nwindow.CMS_MANUAL_INIT = true\n// Usage with import from npm package\nimport CMS, { init } from 'netlify-cms'\n// Usage with script tag\nconst { CMS, initCMS: init } = window\n/**\n * Initialize without passing in config - equivalent to just importing\n * Netlify CMS the old way.\n */\ninit()\n/**\n * Optionally pass in a config object. This object will be merged into\n * `config.yml` if it exists, and any portion that conflicts with\n * `config.yml` will be overwritten. Arrays will be replaced during merge,\n * not concatenated.\n *\n * For example, the code below contains an incomplete config, but using it,\n * your `config.yml` can be missing its backend property, allowing you\n * to set this property at runtime.\n */\ninit({\n  config: {\n    backend: {\n      name: 'git-gateway',\n    },\n  },\n})\n/**\n * Optionally pass in a complete config object and set a flag\n *  (`load_config_file: false`) to ignore the `config.yml`.\n *\n * For example, the code below contains a complete config. The\n * `config.yml` will be ignored when setting `load_config_file` to false.\n * It is not required if the `config.yml` file is missing to set\n * `load_config_file`, but will improve performance and avoid a load error.\n */\ninit({\n  config: {\n    backend: {\n      name: 'git-gateway',\n    },\n    load_config_file: false,\n    media_folder: \"static/images/uploads\",\n    public_folder: \"/images/uploads\",\n    collections: [\n      { label: \"Blog\", name: \"blog\", folder: \"_posts/blog\", create: true, fields: [\n        { label: \"Title\", name: \"title\", widget: \"string\" },\n        { label: \"Publish Date\", name: \"date\", widget: \"datetime\" },\n        { label: \"Featured Image\", name: \"thumbnail\", widget: \"image\" },\n        { label: \"Body\", name: \"body\", widget: \"markdown\" },\n      ]},\n    ],\n  },\n})\n// The registry works as expected, and can be used before or after init.\nCMS.registerPreviewTemplate(...);
\n

Raw CSS in registerPreviewStyle

\n

registerPreviewStyle can now accept a CSS string, in addition to accepting a url. The feature is activated by passing in an object as the second argument, with raw set to a truthy value. This is critical for integrating with modern build tooling. Here's an example using webpack:

\n
/**\n * Assumes a webpack project with `sass-loader` and `css-loader` installed.\n * Takes advantage of the `toString` method in the return value of `css-loader`.\n */\nimport CMS from 'netlify-cms';\nimport styles from '!css-loader!sass-loader!../main.scss';\nCMS.registerPreviewStyle(styles.toString(), { raw: true });
\n

Squash merge GitHub pull requests

\n

When using the Editorial Workflow with the github or GitHub-connected git-gateway backends, Netlify CMS creates a pull request for each unpublished entry. Every time the unpublished entry is changed and saved, a new commit is added to the pull request. When the entry is published, the pull request is merged, and all of those commits are added to your project commit history in a merge commit.

\n

The squash merge option causes all commits to be \"squashed\" into a single commit when the pull request is merged, and the resulting commit is rebased onto the target branch, avoiding the merge commit altogether.

\n

To enable this feature, you can set the following option in your Netlify CMS config.yml:

\n
backend:\n  squash_merges: true
\n

Commit Message Templates

\n

You can customize the templates used by Netlify CMS to generate commit messages by setting the commit_messages option under backend in your Netlify CMS config.yml.

\n

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.

\n

Setting up your Netlify CMS config.yml to recreate the default values would look like this:

\n
backend:\n  commit_messages:\n    create: Create {{collection}} “{{slug}}”\n    update: Update {{collection}} “{{slug}}”\n    delete: Delete {{collection}} “{{slug}}”\n    uploadMedia: Upload “{{path}}”\n    deleteMedia: Delete “{{path}}”\n    openAuthoring: '{{message}}'
\n

Netlify CMS generates the following commit types:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Commit typeWhen is it triggered?Available template tags
createA new entry is createdslug, path, collection
updateAn existing entry is changedslug, path, collection
deleteAn exising entry is deletedslug, path, collection
uploadMediaA media file is uploadedpath
deleteMediaA media file is deletedpath
openAuthoringA commit is made via a forked repositorymessage, author-login, author-name
\n

Template tags produce the following output:

\n\n

Image widget file size limit

\n

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.

\n

Example config:

\n
- label: 'Featured Image'\n  name: 'thumbnail'\n  widget: 'image'\n  default: '/uploads/chocolate-dogecoin.jpg'\n  media_library:\n    config:\n      max_file_size: 512000 # in bytes, only for default media library
\n

Registering to CMS Events

\n

You can execute a function when a specific CMS event occurs.

\n

Example usage:

\n
CMS.registerEventListener({\n  name: 'prePublish',\n  handler: ({ author, entry }) => console.log(JSON.stringify({ author, data: entry.get('data') })),\n});\n\nCMS.registerEventListener({\n  name: 'postPublish',\n  handler: ({ author, entry }) => console.log(JSON.stringify({ author, data: entry.get('data') })),\n});\n\nCMS.registerEventListener({\n  name: 'preUnpublish',\n  handler: ({ author, entry }) => console.log(JSON.stringify({ author, data: entry.get('data') })),\n});\n\nCMS.registerEventListener({\n  name: 'postUnpublish',\n  handler: ({ author, entry }) => console.log(JSON.stringify({ author, data: entry.get('data') })),\n});
\n

Note: Supported events are prePublish, postPublish, preUnpublish and postUnpublish.

\n

Dynamic Default Values

\n

When linking to /admin/#/collections/posts/new you can pass URL parameters to pre-populate an entry.

\n

For example given the configuration:

\n
collections:\n  - name: posts\n    label: Posts\n    folder: content/posts\n    create: true\n    fields:\n      - label: Title\n        name: title\n        widget: string\n      - label: Object\n        name: object\n        widget: object\n        fields:\n          - label: Title\n            name: title\n            widget: string\n      - label: body\n        name: body\n        widget: markdown
\n

clicking the following link: /#/collections/posts/new?title=first&object.title=second&body=%23%20content

\n

will open the editor for a new post with the title field populated with first, the nested object.title field\nwith second and the markdown body field with # content.

\n

Note: URL Encoding might be required for certain values (e.g. in the previous example the value for body is URL encoded).

"},"nav":{"group":[{"fieldValue":"backends","edges":[{"node":{"fields":{"slug":"/docs/backends-overview/"},"frontmatter":{"title":"Overview","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/git-gateway-backend/"},"frontmatter":{"title":"Git Gateway","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/bitbucket-backend/"},"frontmatter":{"title":"Bitbucket","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/github-backend/"},"frontmatter":{"title":"GitHub","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/gitlab-backend/"},"frontmatter":{"title":"GitLab","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/test-backend/"},"frontmatter":{"title":"Test","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/external-oauth-clients/"},"frontmatter":{"title":"External OAuth Clients","group":"backends"},"tableOfContents":""}}]},{"fieldValue":"contributing","edges":[{"node":{"fields":{"slug":"/docs/contributor-guide/"},"frontmatter":{"title":"Contributor Guide","group":"contributing"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/writing-style-guide/"},"frontmatter":{"title":"Writing Style Guide","group":"contributing"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/architecture/"},"frontmatter":{"title":"Architecture","group":"contributing"},"tableOfContents":""}}]},{"fieldValue":"customization","edges":[{"node":{"fields":{"slug":"/docs/custom-widgets/"},"frontmatter":{"title":"Creating Custom Widgets","group":"customization"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/customization/"},"frontmatter":{"title":"Creating Custom Previews","group":"customization"},"tableOfContents":""}}]},{"fieldValue":"features","edges":[{"node":{"fields":{"slug":"/docs/deploy-preview-links/"},"frontmatter":{"title":"Deploy Preview Links","group":"features"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/open-authoring/"},"frontmatter":{"title":"Open Authoring","group":"features"},"tableOfContents":""}}]},{"fieldValue":"guides","edges":[{"node":{"fields":{"slug":"/docs/gatsby/"},"frontmatter":{"title":"Gatsby","group":"guides"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/hugo/"},"frontmatter":{"title":"Hugo","group":"guides"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/nextjs/"},"frontmatter":{"title":"NextJS","group":"guides"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/nuxt/"},"frontmatter":{"title":"Nuxt","group":"guides"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/jekyll/"},"frontmatter":{"title":"Jekyll","group":"guides"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/middleman/"},"frontmatter":{"title":"Middleman","group":"guides"},"tableOfContents":""}}]},{"fieldValue":"media","edges":[{"node":{"fields":{"slug":"/docs/cloudinary/"},"frontmatter":{"title":"Cloudinary","group":"media"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/netlify-large-media/"},"frontmatter":{"title":"Netlify Large Media","group":"media"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/uploadcare/"},"frontmatter":{"title":"Uploadcare","group":"media"},"tableOfContents":""}}]},{"fieldValue":"reference","edges":[{"node":{"fields":{"slug":"/docs/configuration-options/"},"frontmatter":{"title":"Configuration Options","group":"reference"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/widgets/"},"frontmatter":{"title":"Widgets","group":"reference"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/beta-features/"},"frontmatter":{"title":"Beta Features!","group":"reference"},"tableOfContents":""}}]},{"fieldValue":"start","edges":[{"node":{"fields":{"slug":"/docs/intro/"},"frontmatter":{"title":"Introduction","group":"start"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/start-with-a-template/"},"frontmatter":{"title":"Start with a Template","group":"start"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/add-to-your-site/"},"frontmatter":{"title":"Add to Your Site","group":"start"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/collection-types/"},"frontmatter":{"title":"Collection Types","group":"start"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/update-the-cms-version/"},"frontmatter":{"title":"Update the CMS Version","group":"start"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/examples/"},"frontmatter":{"title":"Examples","group":"start"},"tableOfContents":""}}]}]},"menu":{"siteMetadata":{"menu":{"docs":[{"name":"start","title":"Quick Start"},{"name":"backends","title":"Backends"},{"name":"features","title":"Features"},{"name":"reference","title":"Reference"},{"name":"media","title":"Media"},{"name":"guides","title":"Guides"},{"name":"customization","title":"Customization"},{"name":"contributing","title":"Contributing"}]}}},"widgets":{"edges":[{"node":{"frontmatter":{"title":"boolean","label":"Boolean"},"html":"

The boolean widget translates a toggle switch input to a true/false value.

\n"}},{"node":{"frontmatter":{"title":"code","label":"Code"},"html":"

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.

\n"}},{"node":{"frontmatter":{"title":"date","label":"Date"},"html":"

Deprecation notice: the date widget has been deprecated and will be removed in the next major release. Please use the datetime widget instead.

\n

The date widget translates a date picker input to a date string. For saving date and time together, use the datetime widget.

\n"}},{"node":{"frontmatter":{"title":"datetime","label":"DateTime"},"html":"

The datetime widget translates a datetime picker to a datetime string. For saving the date only, use the date widget.

\n"}},{"node":{"frontmatter":{"title":"file","label":"File"},"html":"

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.

\n"}},{"node":{"frontmatter":{"title":"hidden","label":"Hidden"},"html":"

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.

\n"}},{"node":{"frontmatter":{"title":"image","label":"Image"},"html":"

The image widget allows editors to upload an image or select an existing one from the media library. The path to the image file will be saved to the field as a string.

\n"}},{"node":{"frontmatter":{"title":"list","label":"List"},"html":"

The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. map a user-provided string with a comma delimiter into a list. You can choose any widget as a child of a list widget—even other lists.

\n"}},{"node":{"frontmatter":{"title":"map","label":"Map"},"html":"

The map widget allows you to edit spatial data using an interactive map. Spatial data is saved as a GeoJSON string in WGS84 projection and is limited to a single geometry.

\n"}},{"node":{"frontmatter":{"title":"markdown","label":"Markdown"},"html":"

The markdown widget provides a full fledged text editor - which is based on slate - that allows users to format text with features such as headings and blockquotes. Users are also allowed to write in markdown by simply flipping a switch.

\n

Please note: If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field body so the CMS recognizes it and saves the file accordingly.

\n\n

This would render as:

\n

\"Markdown

\n

Please note: The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator's documentation for more information about rendering markdown.

"}},{"node":{"frontmatter":{"title":"number","label":"Number"},"html":"

The number widget uses an HTML number input, saving the value as a string, integer, or floating point number.

\n"}},{"node":{"frontmatter":{"title":"object","label":"Object"},"html":"

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

\n"}},{"node":{"frontmatter":{"title":"relation","label":"Relation"},"html":"

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.

\n"}},{"node":{"frontmatter":{"title":"select","label":"Select"},"html":"

The select widget allows you to pick a string value from a dropdown menu.

\n"}},{"node":{"frontmatter":{"title":"string","label":"String"},"html":"

The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget.

\n"}},{"node":{"frontmatter":{"title":"text","label":"Text"},"html":"

The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget.

\n"}}]}},"pageContext":{"slug":"/docs/beta-features/"}}}