From 98b217f616f232b7fb3305f671fdd8860c1a77f7 Mon Sep 17 00:00:00 2001 From: Ian Storm Taylor Date: Tue, 12 Jul 2016 22:24:07 -0700 Subject: [PATCH] update docs --- Contributing.md | 8 ++++---- docs/concepts/plugins.md | 4 ++-- docs/concepts/statelessness-and-immutability.md | 4 ++-- docs/concepts/the-document-model.md | 8 ++++---- docs/concepts/the-selection-model.md | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/Contributing.md b/Contributing.md index 79432334e..680952951 100644 --- a/Contributing.md +++ b/Contributing.md @@ -4,7 +4,7 @@ Want to contribute to Slate? That would be awesome! -#### Running Tests +### Running Tests To run the examples, you need to have the Slate repository cloned to your computed. After that, you need to `cd` into the directory where you cloned it, and run `make install` to install of its dependencies from `npm`. @@ -24,7 +24,7 @@ make watch-dist ``` -#### Running Examples +### Running Examples To run the examples, you need to have the Slate repository cloned to your computed. After that, you need to `cd` into the directory where you cloned it, and run `make install` to install of its dependencies from `npm`. @@ -45,14 +45,14 @@ make watch-examples ``` -#### Pull Requests +### Pull Requests All pull requests are super welcomed and greatly appreciated! Easy issues are marked with an [`easy-one`](https://github.com/ianstormtaylor/slate/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy-one) label if you're looking for a simple place to get familiar with the code base. Please include tests and docs with every pull request! -#### Browser Support +### Browser Support Slate aims to targeted all of the modern browsers, and eventually the modern mobile platforms. Right now browser support is limited to the latest versions of [Chrome](https://www.google.com/chrome/browser/desktop/), [Firefox](https://www.mozilla.org/en-US/firefox/new/), and [Safari](http://www.apple.com/safari/), but if you are interested in adding support for another modern platform, that is welcomed! diff --git a/docs/concepts/plugins.md b/docs/concepts/plugins.md index 09bb884f3..986e9c1c1 100644 --- a/docs/concepts/plugins.md +++ b/docs/concepts/plugins.md @@ -6,14 +6,14 @@ In Slate, all custom logic added to the editor is done via plugins. Plugins have _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 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 +### The Editor Plugin Plugins are so central to Slate's architecture, that the properties of the [``](../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! diff --git a/docs/concepts/statelessness-and-immutability.md b/docs/concepts/statelessness-and-immutability.md index d32a28f06..cae14f179 100644 --- a/docs/concepts/statelessness-and-immutability.md +++ b/docs/concepts/statelessness-and-immutability.md @@ -6,7 +6,7 @@ All of the data in Slate is immutable, thanks to [Immutable.js](https://facebook _To learn more, check out the [`State` model reference](../reference/models/state.md)._ -#### The `onChange` Handler +### The `onChange` Handler Because of Slate's immutability, you don't actually "set" itself a new state when something changes. @@ -15,7 +15,7 @@ Instead, the new state is propagated to the Slate editor's parent component, who _To learn more, check out the [`` component reference](../reference/components/editor.md)._ -# Transforms +### 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. diff --git a/docs/concepts/the-document-model.md b/docs/concepts/the-document-model.md index ebb1e047e..a49769411 100644 --- a/docs/concepts/the-document-model.md +++ b/docs/concepts/the-document-model.md @@ -4,7 +4,7 @@ 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. -#### Node Hierarchy +### 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. @@ -15,19 +15,19 @@ After that, nesting can occur to any depth. `Block` nodes can contain other `Blo Each `Document`, `Block` and `Inline` node implements a [`Node`](../reference/models/node.md) interface, to make working with the nested tree easier. -#### Leaf Text Nodes +### Leaf Text 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. 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 +### Characters & Marks 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). -#### Void Nodes +### 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. diff --git a/docs/concepts/the-selection-model.md b/docs/concepts/the-selection-model.md index 298136294..ce8ca038d 100644 --- a/docs/concepts/the-selection-model.md +++ b/docs/concepts/the-selection-model.md @@ -4,7 +4,7 @@ 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 +### 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. @@ -13,13 +13,13 @@ A selection always refers to text nodes. Such that even if you set a selection r 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 +### 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 +### 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.