From 93e2487c6ebf547aee1b971f7b704427039d0b3a Mon Sep 17 00:00:00 2001
From: Ian Storm Taylor <ian@ianstormtaylor.com>
Date: Sun, 17 Jul 2016 15:37:05 -0700
Subject: [PATCH] add serializer docs

---
 Readme.md                           |   4 +
 docs/reference/Readme.md            |   4 +
 docs/reference/serializers/html.md  |  69 +++++++++++++++
 docs/reference/serializers/plain.md |  35 ++++++++
 docs/reference/serializers/raw.md   | 133 ++++++++++++++++++++++++++++
 5 files changed, 245 insertions(+)
 create mode 100644 docs/reference/serializers/html.md
 create mode 100644 docs/reference/serializers/plain.md
 create mode 100644 docs/reference/serializers/raw.md

diff --git a/Readme.md b/Readme.md
index 5025b59ec..4b923a0a9 100644
--- a/Readme.md
+++ b/Readme.md
@@ -131,6 +131,10 @@ 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)
+  - Serializers
+    - [Html](./docs/reference/serializers/html.md)
+    - [Plain](./docs/reference/serializers/plain.md)
+    - [Raw](./docs/reference/serializers/raw.md) 
   - Plugins
     - [Plugins](./docs/reference/plugins/plugins.md)
     - [Core](./docs/reference/plugins/core.md)
diff --git a/docs/reference/Readme.md b/docs/reference/Readme.md
index b5803ade7..2981cc64f 100644
--- a/docs/reference/Readme.md
+++ b/docs/reference/Readme.md
@@ -18,6 +18,10 @@ This is the full reference documentation for all of the pieces of Slate, broken
   - [State](./models/state.md)
   - [Text](./text.md)
   - [Transform](./models/transform.md)
+- **Serializers**
+  - [Html](./html.md)
+  - [Plain](./plain.md)
+  - [Raw](./raw.md) 
 - **Plugins**
   - [Plugins](./plugins/plugins.md)
   - [Core](./plugins/core.md)
diff --git a/docs/reference/serializers/html.md b/docs/reference/serializers/html.md
new file mode 100644
index 000000000..4b94772a2
--- /dev/null
+++ b/docs/reference/serializers/html.md
@@ -0,0 +1,69 @@
+
+# `Html`
+
+```js
+import { Html } from 'slate'
+```
+
+The `Html` serializer lets you parse and stringify arbitrary HTML content, based on your specific schema's use case. You must pass a series of `rules` to define how your Slate schema should be serialized to and from HTML.
+
+For an example of the `Html` serializer in action, check out the [`paste-html` example](../../examples/paste-html).
+
+- [Example](#example)
+- [Properties](#properties)
+  - [`rules`]
+- [Methods](#methods)
+  - [`deserialize`](#deserialize)
+  - [`serialize`](#serialize)
+- [Rules](#rules)
+  - [Rule Properties](#rule-properties)
+    - [`rule.deserialize`](#ruledeserialize)
+    - [`rule.serialize`](#ruleserialize)
+
+
+## Example
+
+```txt
+The Slate editor gives you full control over the logic you can add.\n
+In its simplest form, when representing plain text, Slate is a glorified <textarea>. But you can augment it to be much more than that.\n
+Check out http://slatejs.org for examples!
+```
+
+
+## Properties
+
+### `rules`
+`Array`
+
+An array of rules to initialize the `Html` serializer with, defining your schema.
+
+
+## Methods
+
+### `Html.deserialize`
+`Html.deserialize(html: String) => State`
+
+Deserialize an HTML `string` into a [`State`](../models/state.md). How the string is deserialized will be determined by the rules that the `Html` serializer was constructed with.
+
+### `Html.serialize`
+`Html.serialize(state: State) => String`
+
+Serialize a `state` into an HTML string. How the string is serialized will be determined by the rules that the `Html` serializer was constructed with.
+
+
+## Rules
+
+To initialize an `Html` serialize, you must pass it an array of rules, defining your schema. Each rule defines how to deserialize and serialize a node or mark, by implementing two functions.
+
+### Rule Properties
+
+Each rule must define two properties:
+
+#### `rule.deserialize`
+`rule.deserialize(el: CheerioElement, next: Function) => Object`
+
+
+#### `rule.serialize`
+`rule.serialize(object: Node || Mark) => ReactElement`
+
+_To implement still..._
diff --git a/docs/reference/serializers/plain.md b/docs/reference/serializers/plain.md
new file mode 100644
index 000000000..9cdbb6b33
--- /dev/null
+++ b/docs/reference/serializers/plain.md
@@ -0,0 +1,35 @@
+
+# `Plain`
+
+```js
+import { Plain } from 'slate'
+```
+
+A serializer that converts a Slate [`State`](../models/state.md) to and from a plain text string.
+
+- [Example](#example)
+- [Static Methods](#methods)
+  - [`Plain.deserialize`](#plaindeserialize)
+  - [`Plain.serialize`](#plainserialize)
+
+
+## Example
+
+```txt
+The Slate editor gives you full control over the logic you can add.\n
+In its simplest form, when representing plain text, Slate is a glorified <textarea>. But you can augment it to be much more than that.\n
+Check out http://slatejs.org for examples!
+```
+
+
+## Methods
+
+### `Plain.deserialize`
+`Plain.deserialize(string: String) => State`
+
+Deserialize a plain text `string` into a [`State`](../models/state.md). A series of blocks will be created by splitting the input string on `\n` characters. Each block is given a type of `'line'`.
+
+### `Plain.serialize`
+`Plain.serialize(state: State) => String`
+
+Serialize a `state` into a plain text string. Each direct child block of the document will be separated by a `\n` character.
diff --git a/docs/reference/serializers/raw.md b/docs/reference/serializers/raw.md
new file mode 100644
index 000000000..9dac1e053
--- /dev/null
+++ b/docs/reference/serializers/raw.md
@@ -0,0 +1,133 @@
+
+# `Raw`
+
+```js
+import { Raw } from 'slate'
+```
+
+The raw JSON serialized that ships by default with Slate. It converts a [`State`](../models/state.md) into a JSON object. 
+
+The raw JSON object created will omit default-value properties to reduce the serialized data's size. For example, if the dictionary of [`Data`](../models/data.md) for a [`Node`](../models/node.md) is empty, it will be omitted.
+
+In the raw format, text is represented as "ranges", which are a more compact way to represent the formatting applied to characters than the immutable model Slate uses internally.
+
+- [Example](#example)
+- [Static Methods](#methods)
+  - [`Raw.deserialize`](#rawdeserialize)
+  - [`Raw.serialize`](#rawserialize)
+
+
+## Example
+
+```json
+{
+  "nodes": [
+    {
+      "kind": "block",
+      "type": "paragraph",
+      "nodes": [
+        {
+          "kind": "text",
+          "ranges": [
+            {
+              "text": "The Slate editor gives you "
+            },
+            {
+              "text": "complete",
+              "marks": [
+                {
+                  "type": "italic"
+                }
+              ]
+            },
+            {
+              "text": "control over the logic you can add. For example, it's fairly common to want to add markdown-like shortcuts to editors. So that, when you start a line with \"> \" you get a blockquote that looks like this:"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "kind": "block",
+      "type": "block-quote",
+      "nodes": [
+        {
+          "kind": "text",
+          "ranges": [
+            {
+              "text": "A wise quote."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "kind": "block",
+      "type": "paragraph",
+      "nodes": [
+        {
+          "kind": "text",
+          "ranges": [
+            {
+              "text": "Order when you start a line with \"## \" you get a level-two heading, like this:"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "kind": "block",
+      "type": "heading-two",
+      "nodes": [
+        {
+          "kind": "text",
+          "ranges": [
+            {
+              "text": "Try it out at "
+            }
+          ]
+        },
+        {
+          "kind": "inline",
+          "type": "link",
+          "data": {
+            "href": "http://slatejs.org"
+          },
+          "nodes": [
+            {
+              "kind": "text",
+              "ranges": [
+                {
+                  "text": "http://slatejs.org"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "kind": "text",
+          "ranges": [
+            {
+              "text": "!"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+
+## Methods
+
+### `Raw.deserialize`
+`Raw.deserialize(object: Object) => State`
+
+Deserialize a raw JSON `object` into a [`State`](../models/state.md).
+
+### `Raw.serialize`
+`Raw.serialize(state: State) => Object`
+
+Serialize a `state` into a raw JSON object.