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.
* If the default port (8081) is in use, the proxy server won't start and you will see an error message. In this case, follow [these steps](#configure-the-@staticcms/proxy-server-port-number) before proceeding.
4. Start your local development server (e.g. run `gatsby develop`).
5. Open `http://localhost:<port>/admin` to verify that your can administer your content locally. Replace `<port>` with the port of your local development server. For example Gatsby's default port is `8000`
**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.
Experimental support for GitHub's [GraphQL API](https://developer.github.com/v4/) is now available for the GitHub backend.
**Note: not compatible with Git Gateway.**
GraphQL allows to retrieve data 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.
You can use the GraphQL API for the GitHub backend by setting `backend.use_graphql` to `true` in your CMS config:
```yml
backend:
name: github
repo: owner/repo # replace this with your repo info
use_graphql: true
```
Learn more about the benefits of GraphQL in the [GraphQL docs](https://graphql.org).
## GitLab GraphQL API
Experimental support for GitLab's [GraphQL API](https://docs.gitlab.com/ee/api/graphql/) is now available for the GitLab backend.
**Note: not compatible with Git Gateway.**
GraphQL allows to retrieve data using less individual API requests compared to a REST API.
The current implementation uses the GraphQL API in specific cases, where using the REST API can be slow and lead to exceeding GitLab's rate limits. As we receive feedback and extend the feature, we'll migrate more functionality to the GraphQL API.
You can enable the GraphQL API for the GitLab backend by setting `backend.use_graphql` to `true` in your CMS config:
```yml
backend:
name: gitlab
repo: owner/repo # replace this with your repo info
use_graphql: true
# optional, defaults to 'https://gitlab.com/api/graphql'. Can be used to configure a self hosted GitLab instance.
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`.
## Folder Collections 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:
```yaml
media_folder: static/media
public_folder: /media
```
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.
```yaml
media_folder: static/media
public_folder: /media
collections:
- name: posts
label: Posts
label_singular: 'Post'
folder: content/posts
path: '{{slug}}/index'
media_folder: ''
public_folder: ''
fields:
- label: Title
name: title
widget: string
- label: 'Cover Image'
name: 'image'
widget: '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:
```bash
content
posts
example-post
index.md
image.png
```
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](/docs/configuration-options#slug) and:
*`{{dirname}}` The path to the file's parent directory, relative to the collection's `folder`.
*`{{filename}}` The file name without the extension part.
Before this feature, the [list widget](/docs/widgets/#list) 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 Static CMS.
**Note: this feature does not yet support default previews and requires [registering a preview template](/docs/customization#registerpreviewtemplate) in order to show up in the preview pane.**
To use variable types in the list widget, update your field configuration as follows:
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. Each field definition under `types` must use the `object` widget (this is the default value for
`widget`).
### Additional list widget options
*`types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields.
*`typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`.
*`summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary)
### Example Configuration
The example configuration below imagines a scenario where the editor can add two "types" of content,
either a "carousel" or a "spotlight". Each type has a unique name and set of fields.
Static 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.
You can now provide your own element for Static CMS to mount in by setting the target element's ID as `nc-root`. If Static CMS finds an element with this ID during initialization, it will mount within that element instead of creating its own.
Static 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 Static CMS before it loads, bypassing need for an actual Static CMS `config.yml`. This is important, for example, when creating tight integrations with static site generators.
// The registry works as expected, and can be used before or after init.
CMS.registerPreviewTemplate(...);
```
## Raw CSS in `registerPreviewStyle`
`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:
```js
/**
* Assumes a webpack project with `sass-loader` and `css-loader` installed.
* Takes advantage of the `toString` method in the return value of `css-loader`.
You can customize the templates used by Static CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Static CMS `config.yml`.
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.
The above config will transform the title field to uppercase and format the date field using `YYYY-MM-DD` format.
Available transformations are `upper`, `lower`, `date('<format>')`, `default('defaultValue')`, `ternary('valueForTrue','valueForFalse')` and `truncate(<number>)`/`truncate(<number>, '<string>')`
## Registering to CMS Events
You can execute a function when a specific CMS event occurs.
Nested collections expect the following directory structure:
```bash
content
└── pages
├── authors
│ ├── author-1
│ │ └── index.md
│ └── index.md
├── index.md
└── posts
├── hello-world
│ └── index.md
└── index.md
```
## Remark plugins
You can register plugins to customize [`remark`](https://github.com/remarkjs/remark), the library used by the richtext editor for serializing and deserializing markdown.
```js
// register a plugin
CMS.registerRemarkPlugin(plugin);
// provide global settings to all plugins, e.g. for customizing `remark-stringify`
