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

misc edits in /docs; mostly style, grammar, consistency (#489)

Browse Source 
* misc edits in /docs; mostly style, grammar, consistency

* changes per reviewers requests

* removed .md ext from links in 2 files per request
This commit is contained in:
Rich Cook 2017-07-26 22:29:29 -05:00 committed by Jessica Parsons
parent b283f6931f
commit 6ad6bfd094
10 changed files with 83 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/architecture.md
View File

@ -1,12 +1,12 @@
# Technical Architecture
Netlify CMS is a React Application, using Redux for state management with immutable data structures (immutable.js).
Netlify CMS is a React application, using Redux for state management with immutable data structures (immutable.js).
The core abstractions for content editing are `collections`, `entries` and `widgets`.
Each `collection` represents a collection of entries. This can either be a collection of similar entries with the same structure, or a set of entries where each has their own structure.
Each `collection` represents a collection of entries. This can either be a collection of similar entries with the same structure, or a set of entries where each has its own structure.
The structure of an entry is defined as a series of fields, each with a `name`, a `label` and a `widget` .
The structure of an entry is defined as a series of fields, each with a `name`, a `label`, and a `widget` .
The `widget` determines the UI widget that the content editor will use when editing this field of an entry, as well as how the content of the field is presented in the editing preview.
@ -15,17 +15,17 @@ Entries are loaded and persisted through a `backend` that will typically represe
## State shape / reducers
**Auth:** Keeps track of the logged state and the current user.
**Config:** Holds the environment configuration (backend type, available collections & fields).
**Config:** Holds the environment configuration (backend type, available collections and fields).
**Collections** List of available collections, their fields and metadata information.
**Entries:** Entries for each field.
**EntryDraft:** Reused for each entry that is edited or created. It holds the entry's temporary data util it's persisted on the backend.
**EntryDraft:** Reused for each entry that is edited or created. It holds the entry's temporary data until it's persisted on the backend.
**Medias:** Keeps references to all media files uploaded by the user during the current session.
## Selectors:
## Selectors
Selectors are functions defined within reducers used to compute derived data from the Redux store. The available selectors are:
**selectEntry:** Selects a single entry, given the collection and a slug.
@ -34,7 +34,7 @@ Selectors are functions defined within reducers used to compute derived data fro
**getAsset:** Selects a single AssetProxy object for the given URI.
## Value Objects:
## Value Objects
**AssetProxy:** AssetProxy is a Value Object that holds information regarding an asset file (such as an image, for example), whether it's persisted online or held locally in cache.
For a file persisted online, the AssetProxy only keeps information about its URI. For local files, the AssetProxy will keep a reference to the actual File object while generating the expected final URIs and on-demand blobs for local preview.
@ -42,20 +42,19 @@ For a file persisted online, the AssetProxy only keeps information about its URI
The AssetProxy object can be used directly inside a media tag (such as `<img>`), as it will always return something that can be used by the media tag to render correctly (either the URI for the online file or a single-use blob).
## Components structure and Workflows
Components are separated into two main categories: Container components and presentational components.
Components are separated into two main categories: Container components and Presentational components.
### Entry Editing:
### Entry Editing
For either updating an existing entry or creating a new one, the `EntryEditor` is used and the flow is the same:
* When mounted, the `EntryPage` container component dispatches the `createDraft` action, setting the `entryDraft` state to a blank state (in case of a new entry) or to a copy of the selected entry (in case of an edit).
* The `EntryPage` will also render widgets for each field type in the given entry.
* Widgets are used for editing entry fields. There are different widgets for different field types, and they are always defined in a pair containing a `control` and a `preview` component. The control component is responsible for presenting the user with the appropriate interface for manipulating the current field value, while the preview component is responsible for displaying the value with the appropriate styling.
#### Widget components implementation:
The control component receives 3 callbacks as props: `onChange`, `onAddAsset` & `onRemoveAsset`.
* 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.
#### Widget components implementation
The control component receives three (3) callbacks as props: `onChange`, `onAddAsset`, and `onRemoveAsset`.
* 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 are delegated to the backend implementation. The backend will be called with the updated values and a 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.
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.

10
docs/custom-authentication.md
View File

@ -26,8 +26,8 @@ backend:
base_url: https://auth.server.url.com
```
* **name** name of the auth provider, varies by implementation. `github` when using GitHub auth, even with a third party auth client.
* **repo** repo where content is to be stored.
* **api_root (optional)** the API endpoint. Defaults to `https://api.github.com` when used with the `github` provider. Only necessary in certain cases, eg. when using with GitHub Enterprise.
* **site_domain (optional)** sets `site_id` query param sent to API endpoint, defaults to `location.hostname`, minus any port, or `cms.netlify.com` on localhost so that auth "just works" during local development. Sites with custom authentication will often need to set this for local development to work properly.
* **base_url (optional)** OAuth client URL, defaults to `https:/api.netlify.com` as a convenience. This is **required** when using an external OAuth server.
* **name:** name of the auth provider, varies by implementation. `github` when using GitHub auth, even with a third party auth client.
* **repo:** repo where content is to be stored.
* **api_root (optional):** the API endpoint. Defaults to `https://api.github.com` when used with the `github` provider. Only necessary in certain cases, e.g., when using with GitHub Enterprise.
* **site_domain (optional):** sets `site_id` query param sent to API endpoint. Defaults to `location.hostname`, minus any port, or `cms.netlify.com` on localhost so that auth "just works" during local development. Sites with custom authentication will often need to set this for local development to work properly.
* **base_url (optional):** OAuth client URL, defaults to `https:/api.netlify.com` as a convenience. This is **required** when using an external OAuth server.

22
docs/customization.md
View File

@ -1,11 +1,11 @@
# Customizing the Preview Pane
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available customization methods are:
The NetlifyCMS exposes a `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available customization methods are:
* **registerPreviewStyle** Register a custom stylesheet to use on the preview pane.
* **registerPreviewTemplate** Registers a template for a collection.
* **registerPreviewStyle:** Register a custom stylesheet to use on the preview pane.
* **registerPreviewTemplate:** Registers a template for a collection.
Explore the [NetlifyCMS GitHub example](https://github.com/netlify/netlify-cms/blob/9ced3f16c8bcc3d1a36773b126842d023c589eaf/example/index.html#L90-L91) has a working example to review on GitHub.
Explore the [NetlifyCMS GitHub example](https://github.com/netlify/netlify-cms/blob/9ced3f16c8bcc3d1a36773b126842d023c589eaf/example/index.html#L90-L91), a working example you can review on GitHub.
### React Components inline interaction
@ -59,10 +59,10 @@ Registers a template for a collection.
* collection: The name of the collection which this preview component will be used for.
* react_component: A React component that renders the collection data. Four props will be passed to your component during render:
* entry: Immutable collection containing the entry data.
* widgetFor: Returns the appropriate widget preview component for a given field.
* [widgetsFor](#lists-and-objects): Returns an array of objects with widgets and associated field data. For use with list and object type entries.
* getAsset: Returns the correct filePath or in-memory preview for uploaded images.
* entry: Immutable collection containing the entry data.
* widgetFor: Returns the appropriate widget preview component for a given field.
* [widgetsFor](#lists-and-objects): Returns an array of objects with widgets and associated field data. For use with list and object type entries.
* getAsset: Returns the correct filePath or in-memory preview for uploaded images.
**Example:**
@ -87,7 +87,7 @@ Registers a template for a collection.
```
### Lists and Objects
The API for accessing the individual fields of list and object type entries is similar to the API
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.
@ -102,7 +102,7 @@ Registers a template for a collection.
<script>
var AuthorsPreview = createClass({
// For list fields, the widgetFor function returns an array of objects
// which you can map over in your template. If our field is a list of
// that you can map over in your template. If our field is a list of
// authors containing two entries, with fields `name` and `description`,
// the return value of `widgetsFor` would look like this:
//
@ -178,7 +178,7 @@ Registers a template for a collection.
### Accessing Metadata
Preview Components also receive an additional prop: `fieldsMetaData`. It contains aditional information (besides the plain plain textual value of each field) that can be useful for preview purposes.
For example, the Relation widget passes the whole selected relation data in fieldsMetaData.
For example, the Relation widget passes the whole selected relation data in `fieldsMetaData`.
```js
export default class ArticlePreview extends React.Component {

7
docs/editorial-workflow.md
View File

@ -10,13 +10,12 @@ Alternatively, you can enable an optional "Editorial Workflow" mode that allows
From a technical perspective, the workflow translates editor UI actions into common Git commands:
Actions in Netlify UI... | Perform these Git actions
Actions in Netlify UI ... | Perform these Git actions
--- | ---
Save draft | Commits to a new branch, 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
## Adding to your site
To enable the editorial workflow, add this line to your `admin/config.yml` file:
@ -27,16 +26,14 @@ publish_mode: editorial_workflow
There are no other configuration options right now. There are always three possible statuses, and new branch names are created according to the pattern `cms/collectionName-entrySlug`.
## 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.
## 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` and a `reducers/editorialWorkflow.js` files.
Furthermore, all editorial workflow state is managed in Redux - there's an `actions/editorialWorkflow.js` file and a `reducers/editorialWorkflow.js` file.

20
docs/extending.md
View File

@ -1,15 +1,15 @@
# Extending With Widgets
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews and editor plugins. The available widget extension methods are:
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews, and editor plugins. The available widget extension methods are:
* **registerWidget** lets you register a custom widget.
* **registerEditorComponent** lets you add a block component to the Markdown editor
* **registerWidget:** lets you register a custom widget.
* **registerEditorComponent:** lets you add a block component to the Markdown editor.
### Writing React Components inline
The registerWidget requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate
The `registerWidget` 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.
Although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, NetlifyCMS exposes two constructs globally to allow you to create components inline: ‘createClass’ and ‘h’ (alias for React.createElement).
However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, NetlifyCMS exposes two constructs globally to allow you to create components inline: ‘createClass’ and ‘h’ (alias for React.createElement).
## `registerWidget`
@ -24,9 +24,9 @@ CMS.registerWidget(name, control, \[preview\])
Param | Type | Description
--- | --- | ---
`name` | string | Widget name, allows this widget to be used via the field `widget` property in config
`control` | React.Component \| string | <ul><li>React component that renders the control, receives the following props: <ul><li>**value:** Current field value</li><li>**onChange**: Callback function to update the field value</li></ul></li><li>Name of a registered widget whose control should be used (includes built in widgets).</li></ul>
`control` | React.Component \| string | <ul><li>React component that renders the control, receives the following props: <ul><li>**value:** Current field value</li><li>**onChange:** Callback function to update the field value</li></ul></li><li>Name of a registered widget whose control should be used (includes built in widgets).</li></ul>
[`preview`] | React.Component, optional | Renders the widget preview, receives the following props: <ul><li>**value:** Current preview value</li><li>**field:** Immutable map of current field configuration</li><li>**metadata:** Immutable map of any available metadata for the current field</li><li>**getAsset:** Function for retrieving an asset url for image/file fields</li><li>**entry:** Immutable Map of all entry data</li><li>**fieldsMetaData:** Immutable map of metadata from all fields.</li></ul>
* **field:** The field type which this widget will be used for.
* **field:** The field type that this widget will be used for.
* **control:** A React component that renders the editing interface for this field. Two props will be passed:
* **value:** The current value for this field.
* **onChange:** Callback function to update the field value.
@ -64,13 +64,13 @@ CMS.registerWidget('categories', CategoriesControl, CategoriesPreview);
## `registerEditorComponent`
Register a block level component for the Markdown editor
Register a block level component for the Markdown editor:
CMS.registerEditorComponent(definition)
**Params**
* **definition:** The component definition, must specify: id, label, fields, patterns, fromBlock, toBlock, toPreview
* **definition:** The component definition; must specify: id, label, fields, patterns, fromBlock, toBlock, toPreview
**Example:**
@ -97,7 +97,7 @@ CMS.registerEditorComponent({
return 'youtube ' + obj.id;
},
// Preview output for this component. Can either be a string or a React component
// (Component gives better render performance)
// (component gives better render performance)
toPreview: function(obj) {
return (
'<img src="http://img.youtube.com/vi/' + obj.id + '/maxresdefault.jpg" alt="Youtube Video"/>'

32
docs/intro.md
View File

@ -2,14 +2,14 @@
Netlify CMS is a Content Management System for static sites, allowing collaborators to create, edit, review, and publish content without writing code or dealing with version control. It brings the ease of WordPress-style editing to the simplicity and speed of static sites.
At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub API. This allows for many advantages, including:
At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub API. This provides many advantages, including:
* **Fast, web-based UI** - with rich-text editing, real-time preview, and drag-and-drop media uploads
* **Platform agnostic** - works with most static site generators
* **Easy installation** - add two files to your site and hook up the backend by including in your build process or linking to our CDN
* **Modern authentication** - using GitHub and JSON web tokens
* **Flexible content types** - specify an unlimited number of content types with custom fields
* **Fully extensible** - create custom-styled previews, UI widgets, and editor plugins
* **Fast, web-based UI:** with rich-text editing, real-time preview, and drag-and-drop media uploads.
* **Platform agnostic:** works with most static site generators.
* **Easy installation:** add two files to your site and hook up the backend by including in your build process or linking to our CDN.
* **Modern authentication:** using GitHub and JSON web tokens.
* **Flexible content types:** specify an unlimited number of content types with custom fields.
* **Fully extensible:** create custom-styled previews, UI widgets, and editor plugins.
# Core Concepts
@ -38,9 +38,9 @@ The JS is also available via npm and can be integrated into your regular build p
### Editorial Workflow
Netlify CMS has an optional [editorial workflow](https://github.com/netlify/netlify-cms/blob/master/docs/editorial-workflow.md) that translates common Git commands into familiar language in a simple UI:
Netlify CMS has an optional [editorial workflow](/docs/editorial-workflow) that translates common Git commands into familiar language in a simple UI:
Actions in Netlify UI... | Perform these Git actions
Actions in Netlify UI ... | Perform these Git actions
--- | ---
Save draft | Commits to a new branch, and opens a pull request
Edit draft | Pushes another commit to the draft branch/pull request
@ -59,8 +59,8 @@ backend:
media_folder: "img/uploads" # Folder where user uploaded files should go
collections: # A list of collections the CMS should be able to edit
- name: "post" # Used in routes, ie.: /admin/collections/:slug/edit
label: "Post" # Used in the UI, ie.: "New Post"
- name: "post" # Used in routes, e.g., /admin/collections/:slug/edit
label: "Post" # Used in the UI, e.g., "New Post"
folder: "_posts" # The path to the folder where the documents are stored
create: true # Allow users to create new documents in this collection
fields: # The fields each document in this collection have
@ -76,7 +76,7 @@ Because Netlify CMS is a wrapper for the GitHub API, the "backend" is a repo sto
### Collections
All content managed by Netlify CMS is organized in Collections—groups of files such as:
All content managed by Netlify CMS is organized in Collections (groups of files), such as:
* blog posts
* portfolio samples
@ -93,11 +93,11 @@ Widgets define the data type and interface for entry fields. Netlify CMS comes w
Netlify CMS exposes a `window.CMS` global object that you can use to register custom widgets, previews, and editor plugins. The available methods are:
* `registerPreviewStyle` - register a custom stylesheet to match the editor preview pane to your site style
* `registerPreviewStyle`: register a custom stylesheet to match the editor preview pane to your site style.
* `registerPreviewTemplate` - registers a template to determine how fields are displayed in the preview, customizable for each collection
* `registerPreviewTemplate`: registers a template to determine how fields are displayed in the preview, customizable for each collection.
* `registerWidget` - registers a custom widget
* `registerWidget`: registers a custom widget.
* `registerEditorComponent` - adds a block component to the Markdown editor
* `registerEditorComponent`: adds a block component to the Markdown editor.

36
docs/quick-start.md
View File

@ -1,10 +1,10 @@
# Quick Start
There are many ways to add Netlify CMS to your static site. This guide will take you through one of the quickest, which takes advantage of Netlify's hosting and authentication provider services.
There are many ways to add Netlify CMS to your static site. This guide will take you through one of the quickest methods, which takes advantage of Netlify's hosting and authentication provider services.
## Storage and Authentication
Netlify CMS relies on the GitHub API for managing files, so you'll need to have your site stored in a GitHub repo. (If you're partial to another Git hosting service, you can file a [feature request](https://github.com/netlify/netlify-cms/issues), or [help us add it](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md).) To connect to the repo and make changes, the app needs to authenticate with the GitHub API. You can roll your own service for doing this, but we're going to use Netlify.
Netlify CMS relies on the GitHub API for managing files, so you'll need to have your site stored in a GitHub repo. (If you're partial to another Git hosting service, you can file a [feature request](https://github.com/netlify/netlify-cms/issues), or [help us add it](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md).) To connect to the repo and make changes, the app needs to authenticate with the GitHub API. You can roll your own service for doing this, but we're going to use Netlify in this example.
### Hosting with Netlify
@ -30,14 +30,14 @@ When you complete the registration, you'll be given a **Client ID** and a **Clie
## App File Structure
All Netlify CMS files are contained in a static `admin` folder, stored at the root of the generated site. Where you store this in the source files depends on your static site generator. Here's the the static file location for a few of the most popular static site generators:
These generators... | store static files in
These generators ... | store static files in
--- | ---
Jekyll, GitBook | `/` (project root)
Hugo | `/static`
Hexo, Middleman | `/source`
Spike | `/views`
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. They're 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!).
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. They're 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](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md)!).
Inside the `admin` folder, you'll create two files:
@ -84,7 +84,7 @@ backend:
This names GitHub as the authentication provider, points to the repo location on github.com, and declares the branch where you want to merge changes. If you leave out the `branch` declaration, it will default to `master`.
### Editorial Workflow
By default, saving a post in the CMS interface will push a commit directly to the branch specified in `backend`. However, you also have the option to enable the [Editorial Workflow](editorial-workflow.md), which adds an interface for drafting, reviewing, and approving posts. To do this, simply add this line to your `config.yml`:
By default, saving a post in the CMS interface will push a commit directly to the branch specified in `backend`. However, you also have the option to enable the [Editorial Workflow](editorial-workflow.md), which adds an interface for drafting, reviewing, and approving posts. To do this, simply add the following line to your `config.yml`:
``` yaml
publish_mode: editorial_workflow
@ -99,7 +99,7 @@ media_folder: "images/uploads" # Media files will be stored in the repo under im
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](#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. It would not, however, work for Hugo, Hexo, Middleman, or others that use a different path. Here's an example that could work for a Hugo site:
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. It would not, however, work for Hugo, Hexo, Middleman or others that use a different path. Here's an example that could work for a Hugo site:
``` yaml
media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads
@ -111,8 +111,9 @@ This configuration adds a new setting, `public_folder`. While `media_folder` spe
>If `public_folder` is not set, Netlify CMS will default to the same value as `media_folder`, adding an opening `/` if one is not included.
### Collections
Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different 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:
Collections define the structure for the different content types on your static site. Since every site is different, the `collections` settings will be very different 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:
``` yaml
---
@ -130,11 +131,11 @@ Given this example, our `collections` settings would look like this:
``` yaml
collections:
- name: "blog" # Used in routes, e.g. /admin/collections/blog
- name: "blog" # Used in routes, e.g., /admin/collections/blog
label: "Blog" # Used in the UI
folder: "_posts/blog" # The path to the folder where the documents are stored
create: true # Allow users to create new documents in this collection
slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template i.e. YYYY-MM-DD-title.md
slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
fields: # The fields for each document, usually in front matter
- {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
- {label: "Title", name: "title", widget: "string"}
@ -172,10 +173,10 @@ Let's break that down:
<td><code>fields</code></td>
<td>Fields listed here are shown as fields in the content editor, then saved as front matter at the beginning of the document (except for <code>body</code>, which follows the front matter). Each field contains the following properties:
<ul>
<li><code>label</code>: Field label in the editor UI</li>
<li><code>name</code>: Field name in the document front matter</li>
<li><code>widget</code>: Determines UI style and value data type (details below)</li>
<li><code>default</code> (optional): Sets a default value for the field</li>
<li><code>label</code>: Field label in the editor UI.</li>
<li><code>name</code>: Field name in the document front matter.</li>
<li><code>widget</code>: Determines UI style and value data type (details below).</li>
<li><code>default</code> (optional): Sets a default value for the field.</li>
</ul>
</td>
</tr>
@ -191,13 +192,10 @@ Widget | UI | Data Type
`number` | text input with `+` and `-` buttons | number
`markdown` | rich text editor with raw option | markdown-formatted string
Based on this example, you can go through the post types in your site and add the appropriate settings to your `config.yml` file. Each post type should be listed as a separate node under the `collections` field.
### Filter
The entries for any collection can be filtered based on the value of a single field. The example
collection below would only show post entries with the value "en" in the language field.
The entries for any collection can be filtered based on the value of a single field. The example collection, below, would only show post entries with the value "en" in the language field.
``` yaml
collections:
@ -214,4 +212,4 @@ collections:
With your configuration complete, it's time to try it out! Go to `yoursite.com/admin` and complete the login prompt to access the admin interface. To add users, simply add them as collaborators on the GitHub repo.
Happy posting!
Happy posting!

2
docs/test-drive.md
View File

@ -1,6 +1,6 @@
# Take a test drive
You can easily try out Netlify CMS by running it on a pre-configured starter site. Our example in the intro is the [Kaldi small business Hugo template](https://github.com/netlify-templates/kaldi-hugo-cms-template). Use the deploy button below to build and deploy your own copy of the repository:
You can easily try out Netlify CMS by running it on a pre-configured starter site. Our example in the [intro](/docs/intro) is the [Kaldi small business Hugo template](https://github.com/netlify-templates/kaldi-hugo-cms-template). Use the deploy button below to build and deploy your own copy of the repository:
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/kaldi-hugo-cms-template)

10
docs/validation.md
View File

@ -1,6 +1,6 @@
# Collection Field Validation
## Available validations to use on config.yaml:
## Available validations to use on `config.yml`:
- Presence: By default all widgets are required, unless specified in the config. Example:
`- {label: "Subtitle", name: "subtitle", widget: "string", required: false}`
@ -9,7 +9,7 @@
`- {label: "Title", name: "title", widget: "string", pattern: [".{10,}", "Should have more than 10 characters"] }`
## Advanced Guide (For widget authors).
## Advanced Guide (For widget authors)
The widget control can optionally implement an `isValid` method to perform custom validations, in addition to presence and pattern. The `isValid` method will be automatically called, and it can return either a boolean value, an object with an error message or a promise. Examples:
@ -32,7 +32,7 @@ Existing error:
};
```
**Object with `error` (Useful for returning custom error messages)**
**Object with `error` (useful for returning custom error messages)**
Existing error:
```javascript
@ -43,7 +43,7 @@ Existing error:
```
**Promise**
You can also return a promise from isValid. While the promise is pending, the widget will be marked as in error. When the promise resolves, the error is automatically cleared.
You can also return a promise from `isValid`. While the promise is pending, the widget will be marked as "in error". When the promise resolves, the error is automatically cleared.
```javascript
isValid = () => {
@ -51,4 +51,4 @@ You can also return a promise from isValid. While the promise is pending, the wi
};
```
Note: Do not create a promise inside isValid - isValid is called right before trying to persist. This means that even if a previous promise was already resolved, when the user hits 'save', `isValid` will be called again - if it returns a new Promise it will be immediately marked as in error until the new promise resolves.
Note: Do not create a promise inside `isValid` - `isValid` is called right before trying to persist. This means that even if a previous promise was already resolved, when the user hits 'save', `isValid` will be called again. If it returns a new promise, it will be immediately marked as "in error" until the new promise resolves.

4
docs/widgets.md
View File

@ -13,8 +13,8 @@ Widgets define the data type and interface for entry fields. Netlify CMS comes w
| `markdown` | rich text editor | string (markdown) |
| `datetime` | date picker | string (ISO date) |
| `select` | select input (dropdown) | string |
| `image` | file picker w/ drag and drop | image file |
| `file` | file picker w/ drag and drop | file |
| `image` | file picker w/ drag-and-drop | image file |
| `file` | file picker w/ drag-and-drop | file |
| `hidden` | none | string |
| `object` | group of other widgets | Immutable Map containing field values |
| `list` | repeatable group of other widgets | Immutable List of objects containing field values |