Brush up docs, TOC, add section about keys.

docs/README.md

@@ -1,8 +1,29 @@
 # Documentation
 
 * [Getting Started](/docs/getting-started.md)
-  * [Hyperx](/docs/hyperx.md)
-  * [JSX](/docs/jsx.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)
 * [Custom Tags](/docs/custom-tags.md)
 * [Applications](/docs/applications.md)
@@ -45,4 +66,4 @@
     * [root](/docs/api.md#root)
   * [emit](/docs/api.md#emit)
 
-
+-->

docs/api.md

@@ -18,18 +18,19 @@
 
 ## <a name="h"></a> h
 
-Type: <samp>([tag](#h-tag), [data](#h-data), [children](#h-children)): [vnode](#vnode)</samp>
+Type: <samp>([tag](#h-tag), [data](#h-data), [children](#h-children)): [vnode]</samp>
 
-* <a name="h-tag"></a>**tag**: <samp>string | ([props](#h-data), [children](#h-children)): [vnode](#vnode)</samp>
-* <a name="h-data"></a>**data**: <samp>object</samp> with [attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes), [styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference), [events](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers), [lifecycle events](/docs/lifecycle-events.md).
-* <a name="h-children"></a>**children**: <samp>string | Array\<[vnode](#vnode)\>
-* <a name="vnode"></a>**vnode**: a [virtual node](/docs/virtual-nodes.md).
+[vnode]: /docs/virtual-nodes.md
 
-## <a name="app"></a> app
+* <a name="h-tag"></a>tag: <samp>string | ([props](#h-data), [children](#h-children)): [vnode]</samp>
+* <a name="h-data"></a>data: [attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes), [styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference), [events](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers), [lifecycle events](/docs/lifecycle-events.md), etc.
+* <a name="h-children"></a>children: <samp>string | Array\<[vnode]\>
+
+## <a name="app"></a>app
 
 Type: <samp>([props](#app-props))</samp>
 
-* <a name="app-props"></a> **props**
+* <a name="app-props"></a> props
   * [state](#state)
   * [view](#view)
   * [actions](#actions)
@@ -39,84 +40,74 @@ Type: <samp>([props](#app-props))</samp>
 
 <a name="app-props"></a>
 
-### <a name="state"></a> state
+### <a name="state"></a>state
 
-Type: <samp>Any</samp>
+Type: <samp>any</samp>
 
-### <a name="view"></a> view
+### <a name="view"></a>view
 
-Type: <samp>([state](#state), [actions](#actions)): [vnode](#vnode)</samp>
+Type: <samp>([state](#state), [actions](#actions)): [vnode]</samp>
 
-### <a name="actions"></a> actions
-#### <a name="actions-action"></a> [_namespace._]action
+### <a name="actions"></a>actions
+#### <a name="actions-action"></a>[_namespace._]action
 
 Type: <samp>([state](#state), [actions](#actions), [data](#actions-data), [emit](#emit))</samp>
 
-* <a name="actions-data"></a> **data**: the data passed to the action.
-
-```jsx
-actions: {
-  foo: {
-    bar: (state, actions, data, emit) => {}
-  }
-}
-
-actions.foo.bar(data)
-```
+* <a name="actions-data"></a> data: <samp>any</samp>
 
-### <a name="events"></a> events
-#### <a name="events-loaded"></a> loaded
+### <a name="events"></a>events
+#### <a name="events-loaded"></a>loaded
 
 Type: <samp>([state](#state), [actions](#actions), _, [emit](#emit)) | Array\<[Type](#events-loaded)\></samp>
 
 Fired after the view is mounted on the DOM.
 
-#### <a name="events-action"></a> action
+#### <a name="events-action"></a>action
 
 Type: <samp>([state](#state), [actions](#actions), [data](#events-action-data), [emit](#emit)): [data](#events-action-data) | Array\<[Type](#events-action)\></samp>
 
-* <a name="events-action-data"></a>**data**
-  * **name**: the name of the action.
-  * **data**: the data passed to the action.
+* <a name="events-action-data"></a>data
+  * name: <samp>string</samp>
+  * data: <samp>any</samp>
 
 Fired before an action is triggered.
 
-#### <a name="events-update"></a> update
+#### <a name="events-update"></a>update
 
 Type: <samp>([state](#state), [actions](#actions), [data](#events-update-data), [emit](#emit)): [data](#events-update-data) | Array\<[Type](#events-update)\></samp>
 
-* <a name="events-update-data"></a>**data**: the updated fragment of the state.
+* <a name="events-update-data"></a>data: the updated fragment of the state.
 
 Fired before the state is updated.
 
-#### <a name="events-render"></a> render
+#### <a name="events-render"></a>render
 
 Type: <samp>([state](#state), [actions](#actions), [data](#events-render-data), [emit](#emit)): [data](#events-render-data) | Array\<[Type](#events-render)\></samp>
 
-* <a name="events-render-data"></a>**data**: the [view](#view) function.
+* <a name="events-render-data"></a>data: the [view](#view).
 
 Fired before the view is rendered.
 
-### <a name="plugins"></a> plugins
+### <a name="plugins"></a>plugins
 
 Type: <samp>Array\<[Plugin](#plugins-plugin)\></samp>
 
-#### <a name="plugins-plugin"></a> Plugin
+#### <a name="plugins-plugin"></a>Plugin
 
 Type: <samp>([props](#app-props)): [props](#plugin-props)</samp>
 
-* <a name="plugin-props"></a> **props**
+* <a name="plugin-props"></a>props
   * [state](#state)
   * [actions](#actions)
   * [events](#events)
 
-### <a name="root"></a> root
+### <a name="root"></a>root
 
 Type: <samp>[Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) = [document.body](https://developer.mozilla.org/en-US/docs/Web/API/Document/body)</samp>
 
-## <a name="emit"></a> emit
+## <a name="emit"></a>emit
 
 Type: <samp>([event](#emit-event), [data](#emit-data)): [data](#emit-data)</samp>
 
-* <a name="emit-event"></a> **event**: the name of the event.
-* <a name="emit-data"></a> **data**: the data passed to the event.
+* <a name="emit-event"></a>event: <samp>string</samp>
+* <a name="emit-data"></a>data: <samp>any</samp>

docs/applications.md

@@ -1,14 +1,14 @@
 # Applications
 
-To create applications use the <samp>[app](/docs/api#app)</samp> function.
+To create applications use the [app](/docs/api#app) function.
 
 ```jsx
 app({
   view: () => <h1>Hi.</h1>
 })
 ```
 
-The <samp>app</samp> function renders the given view and appends it to <samp>[document.body](https://developer.mozilla.org/en-US/docs/Web/API/Document/body)</samp>.
+The app function renders the given view and appends it to <samp>[document.body](https://developer.mozilla.org/en-US/docs/Web/API/Document/body)</samp>.
 
 To mount the application on a different element, use the [root](/docs/api.md#root) property.
 
@@ -110,7 +110,7 @@ app({
 })
 ```
 
-An action may return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). This enables you to use [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function).
+An action may return a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). This enables you to use [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function).
 
 ```jsx
 const delay = seconds =>
@@ -197,7 +197,7 @@ For a practical example see the implementation of the [Router](https://github.co
 
 ### Custom Events
 
-To create custom events, use the <samp>[emit](/docs/api.md#emit)</samp> function which is passed as the last argument to actions/events.
+To create custom events, use the [emit](/docs/api.md#emit) function which is passed as the last argument to actions/events.
 
 ```jsx
 app({

docs/custom-tags.md

@@ -34,7 +34,7 @@ Custom tags are similar to stateless components in other frameworks.
 
 ## JSX
 
-Custom tags and [JSX](/docs/jsx.md) work well together.
+Custom tags and [JSX](/docs/jsx.md) integrate well together.
 
 ```jsx
 <main id="app">

docs/getting-started.md

@@ -36,7 +36,7 @@ Create an <samp>index.html</samp> file, paste the code below and open it in your
 
 ## How does it work?
 
-The <samp>[h](/docs/api.md#h)</samp> function returns an object that represents a DOM element. This object is known as a [virtual node](/docs/virtual-node.md).
+The [h](/docs/api.md#h) function returns an object that represents a DOM element. This object is known as a [virtual node](/docs/virtual-node.md).
 
 ```js
 {
@@ -46,11 +46,11 @@ The <samp>[h](/docs/api.md#h)</samp> function returns an object that represents
 }
 ```
 
-The <samp>[app](/docs/api.md#app)</samp> function renders the view and mounts it on the DOM.
+The [app](/docs/api.md#app) function renders the view and mounts it on the DOM.
 
 ## Hyperx/JSX
 
-You may prefer [Hyperx](/docs/hyperx.md)/[JSX](/docs/jsx.md) to describe your views and compile them to <samp>h</samp> function calls using a [build pipeline](#build-pipeline).
+You may prefer [Hyperx](/docs/hyperx.md)/[JSX](/docs/jsx.md) to describe your views and compile them to h function calls using a [build pipeline](#build-pipeline).
 
 If you are already using Hyperx, you may skip the compilation step at the expense of slightly inferior performance.
 
@@ -94,7 +94,7 @@ To create applications ready for production you will be using:
 
 ### Why?
 
-To compile [Hyperx](/docs/hyperx.md) or [JSX](/docs/jsx.md) into native HyperApp <samp>[h](/docs/api.md#h)</samp> function calls.
+To compile [Hyperx](/docs/hyperx.md) or [JSX](/docs/jsx.md) into native HyperApp [h](/docs/api.md#h) function calls.
 
 The generated code is smaller and faster than the alternative: sending a parser down the wire and compiling the view in the user's browser.
 

docs/gif-search.md

@@ -83,7 +83,7 @@ if (state.isFetching || text === "") {
 
 Inside <samp>actions.search</samp> we use the <samp>[fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)</samp> API to request a gif URL from Giphy.
 
-When <samp>fetch</samp> is done, we receive the payload with the gif information inside a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+When <samp>fetch</samp> is done, we receive the payload with the gif information inside a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
 ```jsx
 fetch(

docs/hyperx.md

@@ -17,7 +17,7 @@ const hello = html`
 
 ## Setup
 
-We'll use [hyperxify](https://github.com/substack/hyperxify) to transform Hyperx into native HyperApp <samp>[h](/docs/h.md#h)</samp> function calls and a bundler to create a single bundle.js file we can deliver to the browser.
+We'll use [hyperxify](https://github.com/substack/hyperxify) to transform Hyperx into native HyperApp [h](/docs/h.md#h) function calls and a bundler to create a single bundle.js file we can deliver to the browser.
 
 There are caveats, however, the ES6 module syntax is incompatible with hyperxify, so we must use the Node.js require function.
 

docs/jsx.md

@@ -17,7 +17,7 @@ For an in-depth introduction to JSX, see the official [documentation](https://fa
 
 ## Setup
 
-To use JSX with HyperApp, we'll use a compiler to transform JSX into native HyperApp <samp>[h](/docs/h.md#h)</samp> function calls and a bundler to create a single bundle.js file we can deliver to the browser.
+To use JSX with HyperApp, we'll use a compiler to transform JSX into native HyperApp [h](/docs/h.md#h) function calls and a bundler to create a single bundle.js file we can deliver to the browser.
 
 In a new directory, create an <samp>index.html</samp> file:
 

docs/keys.md

@@ -0,0 +1,31 @@
+# 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 added to the list, the position of the keyed element will change. Using a key in this way, makes sure <samp>Hyper</samp> is always inserted in the right position instead of mutating its siblings.
+
+

docs/lifecycle-events.md

@@ -8,25 +8,25 @@ They are useful for starting animations, wrapping third party libraries that req
 
 Type: <samp>([element](https://developer.mozilla.org/en-US/docs/Web/API/Element))</samp>
 
-Called after an element is created and added to the DOM.
+Fired after an element is created and added to the DOM.
 
 ## <a name="onupdate"></a> onupdate
 
 Type: <samp>([element](https://developer.mozilla.org/en-US/docs/Web/API/Element))</samp>
 
-Called when the element's data is updated.
+Fired when the element's data is updated.
 
 ## <a name="onremove"></a> onremove
 
 Type: <samp>([element](https://developer.mozilla.org/en-US/docs/Web/API/Element))</samp>
 
-Called before the element is removed from the DOM.
+Fired before the element is removed from the DOM.
 
 ## Examples
 
-This example shows how to create a [custom tag](/docs/custom-tags.md) to wrap [CodeMirror](https://codemirror.net/).
+This example shows how to create a [custom tag](/docs/custom-tags.md) to wrap the [CodeMirror](https://codemirror.net/) editor.
 
-<a name="cb1"><a/>[View Online](https://hyperapp-code-mirror.glitch.me)
+[Try it online](https://hyperapp-code-mirror.glitch.me)
 
 ```jsx
 const node = document.createElement("div")