From 9af7bb7eb93b55c74cecab99bc048bbbe021f56b Mon Sep 17 00:00:00 2001
From: Robert Riemann <robert@riemann.cc>
Date: Wed, 16 Aug 2017 11:02:48 +0200
Subject: [PATCH] improve documentation of list widget, fixes #505

---
 docs/widgets.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/widgets.md b/docs/widgets.md
index 8934e1e5..022fea5c 100644
--- a/docs/widgets.md
+++ b/docs/widgets.md
@@ -22,6 +22,44 @@ Widgets define the data type and interface for entry fields. Netlify CMS comes w
 
 We’re always adding new widgets, and you can also [create your own](/docs/extending)!
 
+### List Widget
+
+The list widget allows you to map a user-provided string with a comma delimiter into a list. Consider the following example that also demonstrates how to set default values:
+
+```yaml
+collections:
+  - name: posts
+    label: Post
+    folder: "_posts"
+    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
+    create: true
+    fields:
+      - {label: Title, name: title, widget: string, tagname: h1}
+      - {label: Body, name: body, widget: markdown}
+      - {label: Categories, name: categories, widget: list}
+      - {label: Tags, name: tags, widget: list, default: ['term_1', 'term_2']}
+```
+
+Lists of objects are supported as well and require a nested field list.
+
+```yaml
+collections:
+  - name: posts
+    label: Post
+    folder: "_posts"
+    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
+    create: true
+    fields:
+      - {label: Title, name: title, widget: string, tagname: h1}
+      - {label: Body, name: body, widget: markdown}
+      - name: authors
+        label: Authors
+        widget: list
+        fields:
+          - {label: Name, name: name, widget: string}
+          - {label: Description, name: description, widget: markdown}
+```
+
 ### Relation Widget
 
 The relation widget allows you to reference an existing entry from within the entry you're editing. It provides a search input with a list of entries from the collection you're referencing, and the list automatically updates with matched entries based on what you've typed.