mirror/slate
1
0
Fork 0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-09-02 19:52:32 +02:00
Code Issues Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Ian Storm Taylor
2016-07-12 22:24:07 -07:00
parent 30203ab430
commit 98b217f616
5 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
Contributing.md
View File

@@ -4,7 +4,7 @@
Want to contribute to Slate? That would be awesome! 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`. 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`. 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. 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! 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! 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!

4
docs/concepts/plugins.md
View File

@@ -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)._ _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. 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)._ _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 [`<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! 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!

4
docs/concepts/statelessness-and-immutability.md
View File

@@ -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)._ _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. 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 [`<Editor>` component reference](../reference/components/editor.md)._ _To learn more, check out the [`<Editor>` 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. 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.

8
docs/concepts/the-document-model.md
View File

@@ -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. 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. 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. 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. 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. 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). 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. 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.

6
docs/concepts/the-selection-model.md
View File

@@ -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`. 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. 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. 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. 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. 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. 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.