gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update Docs “configuration-options” (#2080)

Browse Source 
Automatically generated. Merged on Netlify CMS.
This commit is contained in:
Shawn Erquhart 2019-02-11 18:38:32 -05:00 committed by GitHub
parent be150158b0
commit 92fc667663
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 69 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
website/content/docs/configuration-options.md
View File

@ -1,9 +1,8 @@
---
title: Configuration Options
weight: 23
group: reference
weight: 23
---
All configuration options for Netlify 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:
@ -18,10 +17,9 @@ To see working configuration examples, you can [start from a template](../start-
You can find details about all configuration options below. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.
## Backend
*This setting is required.*
_This setting is required._
The `backend` option specifies how to access the content for your site, including authentication. Full details and code samples can be found in [Authentication & Backends](../authentication-backends).
@ -43,27 +41,26 @@ publish_mode: editorial_workflow
From a technical perspective, the workflow translates editor UI actions into common Git commands:
Actions in Netlify UI ... | Perform these Git actions
--- | ---
Save draft | Commits to a new branch (named according to the pattern `cms/collectionName-entrySlug`), and opens a pull request
Edit draft | Pushes another commit to the draft branch/pull request
Approve and publish draft | Merges pull request and deletes branch
| Actions in Netlify UI ... | Perform these Git actions |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Save draft | Commits to a new branch (named according to the pattern `cms/collectionName-entrySlug`), and opens a pull request |
| Edit draft | Pushes another commit to the draft branch/pull request |
| Approve and publish draft | Merges pull request and deletes branch |
## Media and Public Folders
*This setting is required.*
_This setting is required._
Netlify 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.
**Options**
- `media_folder` (required): Folder path where uploaded files should be saved, relative to the base of the repo.
- `public_folder` (optional): Folder path where uploaded files 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.
* `media_folder` (required): Folder path where uploaded files should be saved, relative to the base of the repo.
* `public_folder` (optional): Folder path where uploaded files 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.
**Example**
``` yaml
```yaml
media_folder: "static/images/uploads"
public_folder: "/images/uploads"
```
@ -94,7 +91,7 @@ content.
**Example:**
```yaml
display_url: https://your-site.com
site_url: https://your-site.com
```
## Display URL
@ -135,15 +132,15 @@ The `slug` option allows you to change how filenames for entries are created and
`slug` accepts multiple options:
- `encoding`
- `unicode` (default): Sanitize filenames (slugs) according to [RFC3987](https://tools.ietf.org/html/rfc3987) and the [WHATWG URL spec](https://url.spec.whatwg.org/). This spec allows non-ASCII (or non-Latin) characters to exist in URLs.
- `ascii`: Sanitize filenames (slugs) according to [RFC3986](https://tools.ietf.org/html/rfc3986). The only allowed characters are (0-9, a-z, A-Z, `_`, `-`, `~`).
- `clean_accents`: Set to `true` to remove diacritics from slug characters before sanitizing. This is often helpful when using `ascii` encoding.
- `sanitize_replacement`: The replacement string used to substitute unsafe characters, defaults to `-`.
* `encoding`
* `unicode` (default): Sanitize filenames (slugs) according to [RFC3987](https://tools.ietf.org/html/rfc3987) and the [WHATWG URL spec](https://url.spec.whatwg.org/). This spec allows non-ASCII (or non-Latin) characters to exist in URLs.
* `ascii`: Sanitize filenames (slugs) according to [RFC3986](https://tools.ietf.org/html/rfc3986). The only allowed characters are (0-9, a-z, A-Z, `_`, `-`, `~`).
* `clean_accents`: Set to `true` to remove diacritics from slug characters before sanitizing. This is often helpful when using `ascii` encoding.
* `sanitize_replacement`: The replacement string used to substitute unsafe characters, defaults to `-`.
**Example**
``` yaml
```yaml
slug:
encoding: "ascii"
clean_accents: true
@ -152,28 +149,28 @@ slug:
## Collections
*This setting is required.*
_This setting is required._
The `collections` setting is the heart of your Netlify 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 Netlify CMS `config.yml` file.
`collections` accepts a list of collection objects, each with the following options:
- `name` (required): unique identifier for the collection, used as the key when referenced in other contexts (like the [relation widget](../widgets/#relation))
- `identifier_field`: see detailed description below
- `label`: label for the collection in the editor UI; defaults to the value of `name`
- `label_singular`: singular label for certain elements in the editor; defaults to the value of `label`
- `description`: optional text, displayed below the label when viewing a collection
- `file` or `folder` (requires one of these): specifies the collection type and location; details in [Collection Types](../collection-types)
- `filter`: optional filter for `folder` collections; details in [Collection Types](../collection-types)
- `create`: for `folder` collections only; `true` allows users to create new items in the collection; defaults to `false`
- `delete`: `false` prevents users from deleting items in a collection; defaults to `true`
- `extension`: see detailed description below
- `format`: see detailed description below
- `frontmatter_delimiter`: see detailed description under `format`
- `slug`: see detailed description below
- `preview_path`: see detailed description below
- `fields` (required): see detailed description below
- `editor`: see detailed description below
* `name` (required): unique identifier for the collection, used as the key when referenced in other contexts (like the [relation widget](../widgets/#relation))
* `identifier_field`: see detailed description below
* `label`: label for the collection in the editor UI; defaults to the value of `name`
* `label_singular`: singular label for certain elements in the editor; defaults to the value of `label`
* `description`: optional text, displayed below the label when viewing a collection
* `file` or `folder` (requires one of these): specifies the collection type and location; details in [Collection Types](../collection-types)
* `filter`: optional filter for `folder` collections; details in [Collection Types](../collection-types)
* `create`: for `folder` collections only; `true` allows users to create new items in the collection; defaults to `false`
* `delete`: `false` prevents users from deleting items in a collection; defaults to `true`
* `extension`: see detailed description below
* `format`: see detailed description below
* `frontmatter_delimiter`: see detailed description under `format`
* `slug`: see detailed description below
* `preview_path`: see detailed description below
* `fields` (required): see detailed description below
* `editor`: see detailed description below
The last few options require more detailed information.
@ -186,7 +183,7 @@ identifier, you can set `identifier_field` to the name of the other field.
**Example**
``` yaml
```yaml
collections:
- name: posts
identifier_field: name
@ -202,30 +199,29 @@ You may also specify a custom `extension` not included in the list above, as lon
`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
- `toml`: parses and saves files as TOML-formatted data files; saves with `toml` extension by default
- `json`: parses and saves files as JSON-formatted data files; saves with `json` extension by default
- `frontmatter`: parses files and saves files with data frontmatter followed by an unparsed body text (edited using a `body` field); saves with `md` extension by default; default for collections that can't be inferred. Collections with `frontmatter` format (either inferred or explicitly set) can parse files with frontmatter in YAML, TOML, or JSON format. However, they will be saved with YAML frontmatter.
- `yaml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as YAML, followed by unparsed body text. The default delimiter for this option is `---`.
- `toml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as TOML, followed by unparsed body text. The default delimiter for this option is `+++`.
- `json-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved as JSON, followed by unparsed body text. The default delimiter for this option is `{` `}`.
* `yml` or `yaml`: parses and saves files as YAML-formatted data files; saves with `yml` extension by default
* `toml`: parses and saves files as TOML-formatted data files; saves with `toml` extension by default
* `json`: parses and saves files as JSON-formatted data files; saves with `json` extension by default
* `frontmatter`: parses files and saves files with data frontmatter followed by an unparsed body text (edited using a `body` field); saves with `md` extension by default; default for collections that can't be inferred. Collections with `frontmatter` format (either inferred or explicitly set) can parse files with frontmatter in YAML, TOML, or JSON format. However, they will be saved with YAML frontmatter.
* `yaml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as YAML, followed by unparsed body text. The default delimiter for this option is `---`.
* `toml-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved only as TOML, followed by unparsed body text. The default delimiter for this option is `+++`.
* `json-frontmatter`: same as the `frontmatter` format above, except frontmatter will be both parsed and saved as JSON, followed by unparsed body text. The default delimiter for this option is `{` `}`.
`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`](#identifier_field)).
**Available template tags:**
- `{{slug}}`: a url-safe version of the `title` field (or identifier field) for the file
- `{{year}}`: 4-digit year of the file creation date
- `{{month}}`: 2-digit month of the file creation date
- `{{day}}`: 2-digit day of the month of the file creation date
- `{{hour}}`: 2-digit hour of the file creation date
- `{{minute}}`: 2-digit minute of the file creation date
- `{{second}}`: 2-digit second of the file creation date
* `{{slug}}`: a url-safe version of the `title` field (or identifier field) for the file
* `{{year}}`: 4-digit year of the file creation date
* `{{month}}`: 2-digit month of the file creation date
* `{{day}}`: 2-digit day of the month of the file creation date
* `{{hour}}`: 2-digit hour of the file creation date
* `{{minute}}`: 2-digit minute of the file creation date
* `{{second}}`: 2-digit second of the file creation date
**Example:**
@ -233,28 +229,29 @@ For folder collections where users can create new items, the `slug` option speci
slug: "{{year}}-{{month}}-{{day}}_{{slug}}"
```
### `preview_path`
A string representing the path where content in this collection can be found on the live site. This
allows deploy preview links to direct to lead to a specific piece of content rather than the site
root of a deploy preview.
**Available template tags:**
- Any field can be referenced by wrapping the field name in double curly braces, eg. `{{author}}`
- `{{slug}}`: the entire slug for the current entry (not just the url-safe identifier, as is the
* Any field can be referenced by wrapping the field name in double curly braces, eg. `{{author}}`
* `{{slug}}`: the entire slug for the current entry (not just the url-safe identifier, as is the
case with [`slug` configuration](#slug)
The following date based template tags are pulled from a date field in your entry, and may require additional configuration, see [`preview_path_date_field`](#preview_path_date_field) for details. If a date template tag is used and no date can be found, `preview_path` will be ignored.
- `{{year}}`: 4-digit year from entry data
- `{{month}}`: 2-digit month from entry data
- `{{day}}`: 2-digit day of the month from entry data
- `{{hour}}`: 2-digit hour from entry data
- `{{minute}}`: 2-digit minute from entry data
- `{{second}}`: 2-digit second from entry data
* `{{year}}`: 4-digit year from entry data
* `{{month}}`: 2-digit month from entry data
* `{{day}}`: 2-digit day of the month from entry data
* `{{hour}}`: 2-digit hour from entry data
* `{{minute}}`: 2-digit minute from entry data
* `{{second}}`: 2-digit second from entry data
**Example:**
```yaml
collections:
- name: posts
@ -262,6 +259,7 @@ collections:
```
### `preview_path_date_field`
The name of a date field for parsing date-based template tags from `preview_path`. If this field is
not provided and `preview_path` contains date-based template tags (eg. `{{year}}`), Netlify CMS will
attempt to infer a usable date field by checking for common date field names, such as `date`. If you
@ -269,6 +267,7 @@ find that you need to specify a date field, you can use `preview_path_date_field
CMS which field to use for preview path template tags.
**Example:**
```yaml
collections:
- name: posts
@ -281,12 +280,12 @@ The `fields` option maps editor UI widgets to field-value pairs in the saved fil
`fields` accepts a list of collection objects, each with the following options:
- `name` (required): unique identifier for the field, used as the key when referenced in other contexts (like the [relation widget](../widgets/#relation))
- `label`: label for the field in the editor UI; defaults to the value of `name`
- `widget`: defines editor UI and inputs and file field data types; details in [Widgets](../widgets)
- `default`: specify a default value for a field; available for most widget types (see [Widgets](../widgets) for details on each widget type). Please note that field default value only works for folder collection type.
- `required`: specify as `false` to make a field optional; defaults to `true`
- `pattern`: add field validation by specifying a list with a regex pattern and an error message; more extensive validation can be achieved with [custom widgets](../custom-widgets/#advanced-field-validation)
* `name` (required): unique identifier for the field, used as the key when referenced in other contexts (like the [relation widget](../widgets/#relation))
* `label`: label for the field in the editor UI; defaults to the value of `name`
* `widget`: defines editor UI and inputs and file field data types; details in [Widgets](../widgets)
* `default`: specify a default value for a field; available for most widget types (see [Widgets](../widgets) for details on each widget type). Please note that field default value only works for folder collection type.
* `required`: specify as `false` to make a field optional; defaults to `true`
* `pattern`: add field validation by specifying a list with a regex pattern and an error message; more extensive validation can be achieved with [custom widgets](../custom-widgets/#advanced-field-validation)
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.
@ -307,7 +306,7 @@ fields:
This setting changes options for the editor view of the collection. It has one option so far:
- `preview`: set to `false` to disable the preview pane for this collection; defaults to `true`
* `preview`: set to `false` to disable the preview pane for this collection; defaults to `true`
**Example:**