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

Docs: add context and links to documented features (#1477)

Browse Source 
* docs(add-to-your-site): include verbose document links

- add extra references to config.yml

* docs(collection-types): provide consistent examples

- include link to configuration doc
- describe admin UI behaviour when accessing files

* docs(add-to-your-site): make authentication phrasing less biased

- add note regarding core behaviour fetching remote files

* docs(collection-types): add note about configurable branches

* docs(website): add more descriptive language to configuration notes

- include deep links to documentation where applicable

* docs(website): change link titles to match their target content
This commit is contained in:
Enrico Sacchetti 2018-08-07 19:33:47 -04:00 committed by Jessica Parsons
parent f801b19221
commit 90e1b5c681
3 changed files with 49 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
website/content/docs/add-to-your-site.md
View File

@ -136,7 +136,7 @@ rating: 5
This is the post body, where I write about our last chance to party before the Y2K bug destroys us all.
```
Given this example, our `collections` settings would look like this:
Given this example, our `collections` settings would look like this in your NetlifyCMS `config.yml` file:
```yaml
collections:
@ -194,11 +194,11 @@ Let's break that down:
As described above, the `widget` property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value will be saved in the document front matter as the value for the `name` specified for that field. A full listing of available widgets can be found in the [Widgets doc](https://www.netlifycms.org/docs/widgets).
Based on this example, you can go through the post types in your site and add the appropriate settings to your Netlify CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field.
Based on this example, you can go through the post types in your site and add the appropriate settings to your Netlify CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field. See the [Collections reference doc](https://www.netlifycms.org/docs/configuration-options/#collections) for more configuration options.
### 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,7 +214,7 @@ collections:
## Authentication
Now that you have your Netlify CMS files in place and configured, all that's left is to enable authentication. There are [many ways to do this](https://www.netlifycms.org/docs/authentication-backends) (with or without deploying to Netlify), but this example uses Netlify because it's one of the quickest ways to get started.
Now that you have your Netlify CMS files in place and configured, all that's left is to enable authentication. We're using the [Netlify](https://www.netlify.com/) platform here because it's one of the quickest ways to get started, but you can learn about other authentication options in the [Authentication & Backends](https://www.netlifycms.org/docs/authentication-backends) doc.
### Setup on Netlify
@ -265,4 +265,6 @@ If you set your registration preference to "Invite only," you'll need to invite
If you left your site registration open, or for return visits after comfirming an email invitation, you can access your site's CMS at `yoursite.com/admin/`.
**Note**: no matter where you access Netlify CMS — whether running locally, in a staging environment, or in your published site — it will always fetch and commit files in your hosted repository (for example, on GitHub), on the branch you configured in your Netlify CMS config.yml file. This means that content fetched in the admin UI will match the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI will save directly to the hosted repository, even if you're running the UI locally or in staging.
Happy posting!

54
website/content/docs/collection-types.md
View File

@ -14,20 +14,21 @@ Folder collections represent one or more files with the same format, fields, and
Unlike file collections, folder collections have the option to allow editors to create new items in the collection. This is set by the boolean `create` field.
**Note:** Folder collections must have at least one field with the name "title" for creating new entry slugs. That field should use the default "string" widget. The "label" for the field can be any string value.
**Note:** Folder collections must have at least one field with the name `title` for creating new entry slugs. That field should use the default `string` widget. The `label` for the field can be any string value. See the [Collections reference doc](https://www.netlifycms.org/docs/configuration-options/#collections) for details on how collections and fields are configured.
Example:
```yaml
- label: 'Blog'
name: 'blog'
folder: '_posts/blog'
collections:
- label: "Blog"
name: "blog"
folder: "_posts/blog"
create: true
fields:
- { label: 'Title', name: 'title', widget: 'string' }
- { label: 'Publish Date', name: 'date', widget: 'datetime' }
- { label: 'Featured Image', name: 'thumbnail', widget: 'image' }
- { label: 'Body', name: 'body', widget: 'markdown' }
- {label: "Title", name: "title", widget: "string"}
- {label: "Publish Date", name: "date", widget: "datetime"}
- {label: "Featured Image", name: "thumbnail", widget: "image"}
- {label: "Body", name: "body", widget: "markdown"}
```
### Filtered folder collections
@ -67,37 +68,38 @@ A `files` collection contains one or more uniquely configured files. Unlike item
When configuring a `files` collection, each file in the collection is configured separately, and listed under the `files` field of the collection. Each file has its own list of `fields`, and a unique filepath specified in the `file` field (relative to the base of the repo).
**Note:** Files listed in a file collection must already exist in the repo, and must have a valid value for the file type. For example, an empty file works as valid YAML, but a JSON file must have a non-empty value to be valid, such as an empty object.
**Note**: Files listed in a file collection must already exist in the hosted repository branch set in your Netlify CMS [backend configuration](https://www.netlifycms.org/docs/authentication-backends/). Files must also have a valid value for the file type. For example, an empty file works as valid YAML, but a JSON file must have a non-empty value to be valid, such as an empty object.
Example:
```yaml
- label: 'Pages'
name: 'pages'
collections:
- label: "Pages"
name: "pages"
files:
- label: 'About Page'
name: 'about'
file: 'site/content/about.yml'
- label: "About Page"
name: "about"
file: "site/content/about.yml"
fields:
- { label: Title, name: title, widget: string }
- { label: Intro, name: intro, widget: markdown }
- {label: Title, name: title, widget: string}
- {label: Intro, name: intro, widget: markdown}
- label: Team
name: team
widget: list
fields:
- { label: Name, name: name, widget: string }
- { label: Position, name: position, widget: string }
- { label: Photo, name: photo, widget: image }
- label: 'Locations Page'
name: 'locations'
file: 'site/content/locations.yml'
- {label: Name, name: name, widget: string}
- {label: Position, name: position, widget: string}
- {label: Photo, name: photo, widget: image}
- label: "Locations Page"
name: "locations"
file: "site/content/locations.yml"
fields:
- { label: Title, name: title, widget: string }
- { label: Intro, name: intro, widget: markdown }
- {label: Title, name: title, widget: string}
- {label: Intro, name: intro, widget: markdown}
- label: Locations
name: locations
widget: list
fields:
- { label: Name, name: name, widget: string }
- { label: Address, name: address, widget: string }
- {label: Name, name: name, widget: string}
- {label: Address, name: address, widget: string}
```

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

@ -24,6 +24,8 @@ _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).
**Note**: no matter where you access Netlify CMS — whether running locally, in a staging environment, or in your published site — it will always fetch and commit files in your hosted repository (for example, on GitHub), on the branch you configured in your Netlify CMS config.yml file. This means that content fetched in the admin UI will match the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI will save directly to the hosted repository, even if you're running the UI locally or in staging.
## Publish Mode
By default, all entries created or edited in the Netlify CMS are committed directly into the main repository branch.