Add configuration options doc

website/site/content/docs/architecture.md

@@ -56,3 +56,21 @@ For either updating an existing entry or creating a new one, the `EntryEditor` i
 #### Widget components implementation
 The control component receives one (1) callback as a prop: `onChange`.
 * onChange (required): Should be called when the users changes the current value. It will ultimately end up updating the EntryDraft object in the Redux Store, thus updating the preview component.
+* onAddAsset & onRemoveAsset (optionals): If the field accepts file uploads for media (images, for example), these callbacks should be invoked with a `AssetProxy` value object. `onAddAsset` will get the current media stored in the Redux state tree while `onRemoveAsset` will remove it. AssetProxy objects are stored in the `Medias` object and referenced in the `EntryDraft` object on the state tree.
+
+Both control and preview widgets receive a `getAsset` selector via props. Displaying the media (or its URI) for the user should always be done via `getAsset`, as it returns an AssetProxy that can return the correct value for both medias already persisted on the server and cached media not yet uploaded.
+
+The actual persistence of the content and medias inserted into the control component is delegated to the backend implementation. The backend will be called with the updated values and a list of assetProxy objects for each field of the entry, and should return a promise that can resolve into the persisted entry object and the list of the persisted media URIs.
+
+
+## Editorial Workflow implementation
+
+Instead of adding logic to `CollectionPage` and `EntryPage`, the Editorial Workflow is implemented as Higher Order Components, adding UI and dispatching additional actions.
+
+Furthermore, all editorial workflow state is managed in Redux - there's an `actions/editorialWorkflow.js` file and a `reducers/editorialWorkflow.js` file.
+
+### About metadata
+
+Netlify CMS embraces the idea of Git-as-backend for storing metadata. The first time it runs with the editorial_workflow setup, it creates a new ref called `meta/_netlify_cms`, pointing to an empty, orphan tree.
+
+Actual data are stored in individual `json` files committed to this tree.

website/site/content/docs/configuration-options.md

@@ -0,0 +1,147 @@
+---
+title: Configuration Options
+position: 23
+---
+
+# Configuration Options
+
+All configuration options for Netlify CMS are specified in the `config.yml` file, in the folder where you access the editor UI (usually in the `/admin` folder).
+
+To see working configuration examples, you can [start from a template](https://www.netlifycms.org/test-drive) or check out the [CMS demo site](https://cms-demo.netlify.com). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/netlify/netlify-cms/blob/master/example/config.yml) to see how each option was configured.
+
+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.*
+
+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](https://www.netlifycms.org/docs/authentication-backends).
+
+
+## Publish Mode
+
+By default, all entries created or edited in the Netlify CMS are committed directly into the main repository branch.
+
+The `publish_mode` option allows you to enable "Editorial Workflow" mode for more control over the content publishing phases. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live.
+
+You can enable the Editorial Workflow with the following line in `config.yml`:
+
+```yaml
+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
+
+
+## Media and Public Folders
+
+*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.
+
+**Example**
+
+``` yaml
+media_folder: "static/images/uploads"
+public_folder: "/images/uploads"
+```
+
+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`.
+
+
+## Collections
+
+*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 `config.yml`.
+
+`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](https://www.netlifycms.org/docs/widgets/#relation))
+- `Label`: label for the collection in the editor UI; defaults to the value of `name`
+- `file` or `folder` (requires one of these): specifies the collection type and location; details in [Collection Types](https://www.netlifycms.org/docs/collection-types)
+- `filter`: optional filter for `folder` collections; details in [Collection Types](https://www.netlifycms.org/docs/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
+- `slug`: see detailed description below
+- `fields` (required): see detailed description below
+
+The last few options require more detailed information.
+
+### `extension` and `format`
+
+These settings determine how collection files are parsed and saved. Both are optional—Netlify 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 determines the file extension saved for new collection items. It accepts the following values: `yml`, `yaml`, `toml`, `json`, `md`, `markdown`, `html`.
+
+You may also specify a custom `extention` 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
+- `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. On saving, however, they will currently be saved with YAML frontmatter. (Follow [Issue #563](https://github.com/netlify/netlify-cms/issues/563)) to see when this changes.)
+
+
+### `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.)
+
+**Available template tags:**
+
+- `{{slug}}`: a url-safe version of the `title` 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
+
+**Example:**
+
+```yaml
+slug: "{{year}}-{{month}}-{{day}}_{{slug}}"
+```
+
+### `fields`
+
+The `fields` option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in `config.yml` determines their order in the editor UI and in the saved file.
+
+`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](https://www.netlifycms.org/docs/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](https://www.netlifycms.org/docs/widgets)
+- `default`: specify a default value for a field; available for most widget types (see [Widgets](https://www.netlifycms.org/docs/widgets) for details on each widget 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](https://www.netlifycms.org/docs/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.
+
+**Example:**
+
+```yaml
+fields:
+  - label: "Title"
+    name: "title"
+    widget: "string"
+    pattern: ['.{10,}', "Must have at least 20 characters"]
+  - {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
+  - {label: "Featured Image", name: "thumbnail", widget: "image", required: false}
+  - {label: "Body", name: "body", widget: "markdown"}
+```
+

website/site/static/_redirects

@@ -1,3 +1,4 @@
 /docs/custom-authentication /docs/authentication-backends 301
 /docs/extending /docs/custom-widgets 301
-/docs/validation /docs/custom-widgets/#advanced-field-validation 301
+/docs/validation /docs/custom-widgets/#advanced-field-validation 301
+/docs/editorial-workflow /docs/configuration/#publish-mode 301