Update Docs: refactor Collections & migrate Beta Features

website/content/docs/beta-features.md

@@ -62,80 +62,6 @@ backend:
 ```
 
 
-## Folder Collections Path
-
-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.
-* `{{extension}}` The file extension.
-* `{{media_folder}}` The global `media_folder`.
-* `{{public_folder}}` The global `public_folder`.
 
 ## List Widget: Variable Types
 
@@ -451,50 +377,6 @@ with `second` and the markdown `body` field with `# content`.
 
 **Note:** URL Encoding might be required for certain values (e.g. in the previous example the value for `body` is URL encoded).
 
-## Nested Collections
-
-Allows a folder collection to show a nested structure of entries and edit the locations of the entries.
-
-Example configuration:
-
-```yaml
-collections:
-  - name: pages
-    label: Pages
-    label_singular: 'Page'
-    folder: content/pages
-    create: true
-    # adding a nested object will show the collection folder structure
-    nested:
-      depth: 100 # max depth to show in the collection tree
-      summary: '{{title}}' # optional summary for a tree node, defaults to the inferred title field
-    fields:
-      - label: Title
-        name: title
-        widget: string
-      - label: Body
-        name: body
-        widget: markdown
-    # adding a meta object with a path property allows editing the path of entries
-    # moving an existing entry will move the entire sub tree of the entry to the new location
-    meta: { path: { widget: string, label: 'Path', index_file: 'index' } }
-```
-
-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
 

website/content/docs/collection-file.md

@@ -0,0 +1,48 @@
+---
+group: Collections
+weight: 20
+title: File Collections
+---
+
+Collections with type `files` displays in the left sidebar of the Content page of the editor UI along with other types.
+
+A `files` collection contains one or more uniquely configured files. Unlike items in `folder` collections, which repeat the same configuration over all files in the folder, each item in a `files` collection has an explicitly set path, filename, and configuration. This can be useful for unique files with a custom set of fields, like a settings file or a custom landing page with a unique content structure.
+
+When configuring a `files` collection, configure each file in the collection separately, and list them 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 hosted repository branch set in your Decap CMS [backend configuration](/docs/backends-overview). 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
+collections:
+  - label: "Pages"
+    name: "pages"
+    files:
+      - label: "About Page"
+        name: "about"
+        file: "site/content/about.yml"
+        fields:
+          - {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"
+        fields:
+          - {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}
+```
+

website/content/docs/collection-folder.md

@@ -0,0 +1,152 @@
+---
+group: Collections
+weight: 10
+title: Folder Collections
+---
+
+Collections with type `folder` displays in the left sidebar of the Content page of the editor UI along with other types.
+
+Folder collections represent one or more files with the same format, fields, and configuration options, all stored within the same folder in the repository. You might use a folder collection for blog posts, product pages, author data files, etc.
+
+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.
+
+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. If you wish to use a different field as your identifier, set `identifier_field` to the field name. See the [Collections reference doc](/docs/configuration-options/#collections) for details on how collections and fields are configured. If you forget to add this field, you will get an error that your collection "must have a field that is a valid entry identifier".
+
+Example:
+
+```yaml
+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"}
+```
+
+With `identifier_field`:
+
+```yaml
+- label: "Blog"
+  name: "blog"
+  folder: "_posts/blog"
+  create: true
+  identifier_field: name
+  fields:
+    - {label: "Name", name: "name", 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
+
+The entries for any folder collection can be filtered based on the value of a single field. By filtering a folder into different collections, you can manage files with different fields, options, extensions, etc. in the same folder.
+
+The `filter` option requires two fields:
+
+* `field`: The name of the collection field to filter on.
+* `value`: The desired field value.
+
+The example below creates two collections in the same folder, filtered by the `language` field. The first collection includes posts with `language: en`, and the second, with `language: es`.
+
+```yaml
+collections:
+  - label: "Blog in English"
+    name: "english_posts"
+    folder: "_posts"
+    create: true
+    filter: {field: "language", value: "en"}
+    fields:
+      - {label: "Language", name: "language", widget: "select", options: ["en", "es"]}
+      - {label: "Title", name: "title", widget: "string"}
+      - {label: "Content", name: "body", widget: "markdown"}
+  - label: "Blog en Español"
+    name: "spanish_posts"
+    folder: "_posts"
+    create: true
+    filter: {field: "language", value: "es"}
+    fields:
+      - {label: "Lenguaje", name: "language", widget: "select", options: ["en", "es"]}
+      - {label: "Titulo", name: "title", widget: "string"}
+      - {label: "Contenido", name: "body", widget: "markdown"}
+```
+
+
+### Folder Collections Path
+
+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`.
+
+### 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.
+* `{{extension}}` The file extension.
+* `{{media_folder}}` The global `media_folder`.
+* `{{public_folder}}` The global `public_folder`.

website/content/docs/collection-nested.md

@@ -0,0 +1,50 @@
+---
+group: Collections
+weight: 30
+title: Nested Collections (beta)
+---
+
+There is beta support for Folder Collections which can also handle `nested` folder structures.
+
+Nested collections is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory. As it is in beta, please use with discretion.
+
+Example configuration:
+
+```yaml
+collections:
+  - name: pages
+    label: Pages
+    label_singular: 'Page'
+    folder: content/pages
+    create: true
+    # adding a nested object will show the collection folder structure
+    nested:
+      depth: 100 # max depth to show in the collection tree
+      summary: '{{title}}' # optional summary for a tree node, defaults to the inferred title field
+    fields:
+      - label: Title
+        name: title
+        widget: string
+      - label: Body
+        name: body
+        widget: markdown
+    # adding a meta object with a path property allows editing the path of entries
+    # moving an existing entry will move the entire sub tree of the entry to the new location
+    meta: { path: { widget: string, label: 'Path', index_file: 'index' } }
+```
+
+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
+```