Put keys in virtual-nodes.md, re-order TOC.

jorgebucaran · Apr 30, 2017 · 5b8607a · 5b8607a
1 parent 1794706
commit 5b8607a
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 82 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -3,67 +3,20 @@
 * [Getting Started](/docs/getting-started.md)
 * [Hyperx](/docs/hyperx.md)
 * [JSX](/docs/jsx.md)
-* [Virtual Nodes](/docs/virtual-nodes.md)
-* [Custom Tags](/docs/custom-tags.md)
-* [Keys](/docs/keys.md)
 * [Applications](/docs/applications.md)
-  * [View and State](/docs/applications.md#view-and-state)
-  * [Actions](/docs/applications.md#actions)
-  * [Events](/docs/applications.md#events)
-  * [Plugins](/docs/applications.md#plugins)
 * [Lifecycle Events](/docs/lifecycle-events.md)
-* [Router](/docs/router.md)
-* [Tutorials](/docs/tutorials.md)
-  * [Counter](/docs/counter.md)
-  * [Countdown Timer](/docs/countdown-timer.md)
-  * [Gif Search](/docs/gif-search.md)
-* [API](/docs/api.md)
-
-
-<!--
-* [Getting Started](/docs/getting-started.md)
-* [Hyperx](/docs/hyperx.md)
-* [JSX](/docs/jsx.md)
 * [Virtual Nodes](/docs/virtual-nodes.md)
+  * [Keys](/docs/keys.md)
 * [Custom Tags](/docs/custom-tags.md)
-* [Applications](/docs/applications.md)
-  * [View and State](/docs/applications.md#view-and-state)
-  * [Actions](/docs/applications.md#actions)
-    * [Namespaces](/docs/applications.md#namespaces)
-  * [Events](/docs/applications.md#events)
-    * [Custom Events](/docs/applications.md#custom-events)
-  * [Plugins](/docs/applications.md#plugins)
-* [Lifecycle Events](/docs/lifecycle-events.md)
-  * [oncreate](/docs/lifecycle-events.md#oncreate)
-  * [onupdate](/docs/lifecycle-events.md#onupdate)
-  * [onremove](/docs/lifecycle-events.md#onremove)
-* [Router](/docs/router.md)
-  * [actions](/docs/router.md#actions)
-    * [go](/docs/router.md#actions-go)
-  * [state](/docs/router.md#state)
-    * [params](/docs/router.md#state-params)
-    * [match](/docs/router.md#state-match)
-  * [events](/docs/router.md#events)
-    * [route](/docs/router.md#events-route)
+* [Routing](/docs/routing.md)
 * [Tutorials](/docs/tutorials.md)
-  * [Counter](/docs/counter.md)
-  * [Countdown Timer](/docs/countdown-timer.md)
-  * [Gif Search](/docs/gif-search.md)
 * [API](/docs/api.md)
   * [h](/docs/api.md#h)
   * [app](/docs/api.md#app)
     * [state](/docs/api.md#state)
     * [view](/docs/api.md#view)
     * [actions](/docs/api.md#actions)
-      * [[_namespace._]action](/docs/api.md#actions-action)
     * [events](/docs/api.md#events)
-      * [loaded](/docs/api.md#events-loaded)
-      * [action](/docs/api.md#events-action)
-      * [update](/docs/api.md#events-update)
-      * [render](/docs/api.md#events-render)
     * [plugins](/docs/api.md#plugins)
-      * [Plugin](/docs/api.md#plugins-plugin)
     * [root](/docs/api.md#root)
   * [emit](/docs/api.md#emit)
-
--->
diff --git a/docs/keys.md b/docs/keys.md
diff --git a/docs/router.md → docs/routing.md b/docs/router.md → docs/routing.md
@@ -1,4 +1,4 @@
-# Router
+# Routing
 
 To add routing to your application, use the Router plugin.
 

diff --git a/docs/virtual-nodes.md b/docs/virtual-nodes.md
@@ -68,5 +68,36 @@ data: {
 }
 ```
 
-Attributes also include [lifecycle events](/docs/lifecycle-events.md) and meta data such as [keys](/docs/keys.md).
+Attributes also include [lifecycle events](/docs/lifecycle-events.md) and meta data such as [keys](#keys).
+
+## Keys
+
+Every time your application is rendered, a virtual node tree is created from scratch.
+
+Keys help identify which nodes were added, changed or removed from the new/old tree.
+
+Use keys to tell the render algorithm to re-order the children instead of mutating them.
+
+```jsx
+<ul>
+  {urls.map((url, id) => (
+    <li key={id}>
+      <img src={url} />
+    </li>
+  ))}
+</ul>
+```
+
+For example, use keys to force an element to be created only once.
+
+```jsx
+<ul>
+  <li key="hyper">Hyper</li>
+  <li>Super</li>
+  <li>Ultra</li>
+</ul>
+```
+
+If new elements are added to the list, the position of the keyed element will change. Using a key in this way, we make sure <samp>Hyper</samp> is always inserted in the right position instead of mutating its siblings.
+