update docs

Readme.md

@@ -74,16 +74,16 @@ If you're using Slate for the first time, check out the [Getting Started](./docs
   - Rendering Adjacent Elements in Components
 
 - [**Concepts**](./docs/concepts)
-  - Statelessness & Immutability
-  - The Document Model
-  - The Selection Model
-  - Plugins
+  - [Statelessness & Immutability](./docs/concepts/statelessness-and-immutability.md)
+  - [The Document Model](./docs/concepts/the-document-model.md)
+  - [The Selection Model](./docs/concepts/the-selection-model.md)
+  - [Plugins](./docs/concepts/plugins.md)
 
 - [**Reference**](./docs/reference)
-  - **Components**
+  - Components
     - [Editor](./docs/reference/components/editor.md)
     - [Placeholder](./docs/reference/components/placeholder.md)
-  - **Models**
+  - Models
     - [Block](./docs/reference/models/block.md)
     - [Character](./docs/reference/models/character.md)
     - [Data](./docs/reference/data.md)
@@ -95,7 +95,7 @@ If you're using Slate for the first time, check out the [Getting Started](./docs
     - [State](./docs/reference/models/state.md)
     - [Text](./docs/reference/text.md)
     - [Transform](./docs/reference/models/transform.md)
-  - **Plugins**
+  - Plugins
     - [Plugins](./docs/reference/plugins/plugins.md)
     - [Core](./docs/reference/plugins/core.md)
 

docs/concepts/plugins.md

@@ -1,5 +1,20 @@
 
-### Plugins
+# Plugins
 
-- everything is a plugin, even core is one
-- the editor's props become the highest-priority plugin
+In Slate, all custom logic added to the editor is done via plugins. Plugins have complete control over the schema, the behaviors, and the rendering of the components of the editor. Slate encourages you to break up code into small, reusable modules that can be shared with others, and easily reasoned about.
+
+_To learn more, check out the [Using Plugins guide](../guides/using-plugins.md), or the [Plugins reference](../reference/plugins/plugins.md)._
+
+
+#### The Core Plugin
+
+The "core" plugin that ships with Slate is where the default editing behavior is kept. It performs actions like splitting the current block when `enter` is pressed, or inserting a string of text when the user pastes from their clipboard. But it stops short of anything opinionated, leaving that for userland plugins to add.
+
+_To learn more, check out the [Core Plugin reference](../reference/plugins/core.md)._
+
+
+#### The Editor Plugin
+
+Plugins are so central to Slate's architecture, that the properties of the [`<Editor>`](../reference/components/editor.md) that allow you to add custom functionality (eg. `onKeyDown` or `onPaste`) are actually implemented as a plugin too. All of those properties actually just create an implicity, top-priority plugin that gets added at the beginning of the editor's plugin stack. But you'd never even know it!
+
+_To learn more, check out the [`<Editor>` component reference](../reference/components/editor.md)._

docs/concepts/statelessness-and-immutability.md

@@ -1,5 +1,24 @@
 
 # Statelessness & Immutability
 
-- all the data is immutable, for performance
-- changes propagated up through the single `onChange` handler
+All of the data in Slate is immutable, thanks to [Immutable.js](https://facebook.github.io/immutable-js/). This makes it possible to achieve a much greater level of performance, and it makes maintaining a history of changes for undo/redo much simpler.
+
+_To learn more, check out the [`State` model reference](../reference/models/state.md)._
+
+
+#### The `onChange` Handler
+
+Because of Slate's immutability, you don't actually "set" itself a new state when something changes. 
+
+Instead, the new state is propagated to the Slate editor's parent component, who decides what to do with it. Usually, you'll simply give the new state right back to the editor via React's `this.setState()` method, similarly to other internal component state. But that's up to you!
+
+_To learn more, check out the [`<Editor>` component reference](../reference/components/editor.md)._
+
+
+# Transforms
+
+All of the changes in Slate are applied via [`Transforms`](../reference/models/transform.md). This makes it possible to enforce some of the constraints that Slate needs to enforce, like requiring that [all leaf nodes be text nodes](./the-document-model.md#leaf-text-nodes). This also makes it possible to implement collaborative editing, where information about changes must be serialized and sent over the network to other editors.
+
+You should never update the `selection` or `document` of an editor other than by using the [`transform()`](../reference/models/state.md#transform) method of a `State`.
+
+_To learn more, check out the [`Transform` model reference](../reference/models/transform.md)._

docs/concepts/the-document-model.md

@@ -1,63 +1,34 @@
 
-# The Document Model
-
-- recursive, nested tree 
-- document, blocks, and inlines implement node interface
-- blocks and inlines can be nested to any depth
-- blocks contain inlines and text
-- inlines contain text
-- always a text node at the leaves, for selection handling
-- void nodes can't have content, but still have an empty text node
-
-
-
-
-
-
-
 # The Document Model
 
 A big difference between Slate and other rich-text editors is that Slate is built on top of a nested, recursive document model—much like the DOM itself. This means you can build complex components like tables or nested block quotes, just like you can with the regular DOM.
 
-Slate's model is split up into a series of parts:
+
+#### Node Hierarchy
+
+Each Slate document is made up of [`Document`](../reference/models/document.md), [`Block`](../reference/models/block.md), [`Inline`](../reference/models/inline.md) and [`Text`](../reference/models/text.md) nodes—again, very similar to the DOM.
+
+The top-level node of a Slate document is the `Document` node. The `Document` then has child `Block` node children.
+
+After that, nesting can occur to any depth. `Block` nodes can contain other `Block` nodes, or they can contain `Inline` or `Text` nodes. And `Inline` nodes can contain other `Inline` nodes or simply `Text` nodes.
+
+Each `Document`, `Block` and `Inline` node implements a [`Node`](../reference/models/node.md) interface, to make working with the nested tree easier.
 
 
-#### Nodes
+#### Leaf Text Nodes
 
-Just like the DOM, Slate's content is built up of a tree of nested nodes. There are four different types of nodes. At the very top you have a **document** node. At the very ends you have **text** nodes. And in between you have a varying amount of **block** and **inline** nodes.
+One constraint of Slate documents is that the leaf nodes are always `Text` nodes. No `Block` or `Inline` node will ever have no children. It will always have at least an empty text node.
 
-
-###### Document
-
-The **document** node is the top-most node of Slate's content. It serves as a wrapper for all of its child nodes.
-
-A **document** node can only have **block** nodes as its direct children.
-
-
-###### Blocks
-
-**Block** nodes, just like in the DOM, are block-level pieces of content—for example, things like paragraphs, quotes, list items, etc. They can have any combination of other **block** nodes, or **inline** and **text** nodes as their children. 
-
-
-###### Inlines
-
-**Inline** nodes, also like in the dom, are inline-level pieces of content—for example, things like links, hashtags, etc. However, this does _not_ include things like bold, italic or underline. For formatting, Slate uses another concept called [Marks](#characters-marks).
-
-**Inline** nodes can have any combination of other **inline** nodes or **text** nodes as their children, just like in the DOM.
-
-
-###### Text
-
-**Text** nodes are the leaf nodes in Slate. Every branch of the document will always end in a text node, even if it's empty.
+This constraint means that [`Selections`](../reference/models/selection.md) can always refer to text nodes, and many text-node-level operations are always "safe" regardless of the tree's structure.
 
 
 #### Characters & Marks
 
-
-#### Selection
+As the leaves of the tree, `Text` nodes contain both the text content of the document as well as all of the text-level formatting, like **bold** and _italic_. In Slate, that formatting is referred to as [`Marks`](../reference/models/mark.md), and `Marks` are applied to individual [`Characters`](../reference/models/character.md).
 
 
-#### State
+#### Void Nodes
 
+Just like the DOM, Slate's `Block` and `Inline` nodes can be "void" nodes, meaning that they have no content inside of them. When the `isVoid` flag of a node is enabled, it will be specially rendered, to preserve the editing experience that a user expects, without any extra work.
 
-####
+Note though, even though the node is "void", it will still have an empty text node inside of it, as described above.

docs/concepts/the-selection-model.md

@@ -1,5 +1,25 @@
 
 # The Selection Model
 
-- selection is always relative to text nodes (is normalized)
-- "blocks" always refers to the closest block parent
+Slate keeps track of the user's selection in the editor in an immutable data store called a [`Selection`](../reference/models/selection.md). By doing this, it lets Slate manipulate the selection with transforms, but still update it in the DOM on `render`.
+
+
+#### Always References Text
+
+One of the contraints of the Slate document model is that [leaf nodes are always text nodes](./the-document-model.md#leaf-text-nodes). This constraint exists to make selection logic simpler. 
+
+A selection always refers to text nodes. Such that even if you set a selection relative to a non-text node, Slate will automatically correct it for you.
+
+This makes selection's easier to reason about, while still giving us the benefits of a recursive document tree, and it makes for a lot less boilerplate.
+
+
+#### Leaf Blocks
+
+When a selection is used to compute a set of [`Block`](../reference/models/block.md) nodes, by convention those nodes are always the leaf-most `Block` nodes (ie. the lowest `Block` nodes in the tree at their location). This is important, because the nested document model allows for nested `Block` nodes.
+
+This convention makes it much simpler to implement selection and transformation logic, since the user's actions are very often supposed to effect the leaf blocks.
+
+
+#### Trunk Inlines
+
+Unline `Block` nodes, when a selection is used to compute a set of [`Inline`](../reference/models/inline.md) nodes, the trunk-most nodes are used (ie. the highest `Inline` nodes in the tree at their location). This is done for the same reason, that most user actions are supposed to act at the highest level of inline nodes.

docs/concepts/transforms.md

@@ -1,6 +0,0 @@
-
-# Transforms
-
-- no updating of document/selection outside of transforms
-- wrap blocks wraps close to the text
-- wrap inline wraps far from the text