1
0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-01-17 21:49:20 +01:00
slate/Readme.md

115 lines
6.7 KiB
Markdown
Raw Normal View History

2016-06-28 08:42:38 -07:00
2016-06-28 09:17:55 -07:00
2016-06-28 14:47:27 -07:00
<p align="center"><img src="support/banner.png" /></p>
2016-06-28 08:42:38 -07:00
2016-07-06 16:31:28 -07:00
<p align="center">A <em>completely</em> customizable framework <br/>for building rich text editors in the browser.</p>
<br/>
2016-06-28 14:44:46 -07:00
2016-07-12 16:46:40 -07:00
<p align="center"><a href="#principles">Principles</a> · <a href="#examples">Examples</a> · <a href="#plugins">Plugins</a> · <a href="#documentation">Documentation</a> · Contributing</p>
2016-07-06 16:31:28 -07:00
<br/>
2016-06-28 08:51:15 -07:00
2016-07-06 16:48:01 -07:00
Slate lets you build rich, intuitive editors like those in [Medium](https://medium.com/), [Dropbox Paper](https://www.dropbox.com/paper) or [Canvas](https://usecanvas.com/)—which are becoming table stakes for applications on the web—without your codebase getting mired in complexity.
2016-07-06 16:45:01 -07:00
2016-07-06 16:47:38 -07:00
It can do this because all of its logic is implemented with a series of plugins, so you aren't ever constrained by what _is_ or _isn't_ in "core". You can think of it like a pluggable implementation of `contenteditable`, built on top of React and Immutable. It was inspired by libraries like [Draft.js](https://facebook.github.io/draft-js/), [Prosemirror](http://prosemirror.net/) and [Quill](http://quilljs.com/).
2016-06-28 09:28:26 -07:00
2016-06-28 09:35:51 -07:00
_Slate is currently in **beta**, while work is being done on: cross-browser support, atomic node support, and collaboration support. It's useable now, but you might need to pull request one or two fixes for your use case._
2016-06-28 08:42:38 -07:00
2016-07-06 16:35:24 -07:00
<br/>
2016-07-06 16:35:45 -07:00
### Principles
2016-06-28 08:42:38 -07:00
2016-06-30 10:43:24 -07:00
1. **First-class plugins.** The most important part of Slate is that plugins are first-class entities—the core editor logic is even implemented as its own plugin. That means you can _completely_ customize the editing experience, to build complex editors like Medium's or Canvas's without having to fight against the library's assumptions.
2016-06-28 08:42:38 -07:00
2016-06-28 14:51:21 -07:00
2. **Schema-less core.** Slate's core logic doesn't assume anything about the schema of the data you'll be editing, which means that there are no assumptions baked into the library that'll trip you up when you need to go beyond basic usage.
2016-06-28 09:27:00 -07:00
2016-06-30 10:43:24 -07:00
3. **Nested document model.** The document model used for Slate is a nested, recursive tree, just like the DOM itself. This means that creating complex components like tables or nested block quotes are possible for advanced use cases. But it's also easy to keep it simple by only using a single level of hierachy.
2016-06-28 14:38:05 -07:00
2016-07-12 10:47:48 -07:00
4. **Stateless and immutable data.** By using React and Immutable.js, the Slate editor is built in a stateless fashion using immutable data structures, which leads to better performance, and also a much easier time writing plugins.
2016-06-28 14:38:05 -07:00
2016-07-11 12:34:22 -07:00
5. **Intuitive transforms.** Slate's content is edited using "transforms", that are designed to be extremely intuitive to use, so that writing plugins and custom functionality is as simple as possible.
2016-07-12 10:47:48 -07:00
6. **Collaboration-ready data model.** The data model Slate uses—specifically how transforms are applied to the document—has been designed to allow for collaborative editing to be layered on top, so you won't need to rethink everything if you decide to make your editor collaborative. (More work is required on this!)
2016-06-28 14:38:05 -07:00
2016-07-06 16:35:24 -07:00
<br/>
2016-07-06 16:35:45 -07:00
### Examples
2016-06-28 08:42:38 -07:00
2016-06-28 09:27:00 -07:00
To get a sense for how you might use Slate, check out a few of the examples:
2016-06-28 08:42:38 -07:00
2016-06-28 16:00:05 -07:00
- [**Plain text**](examples/plain-text) — showing the most basic case: a glorified `<textarea>`.
- [**Rich text**](examples/rich-text) — showing the features you'd expect from a basic editor.
- [**Auto-markdown**](examples/auto-markdown) — showing how to add key handlers for Markdown-like shortcuts.
- [**Links**](examples/links) — showing how wrap text in inline nodes with associated data.
2016-07-06 15:13:15 -07:00
- [**Images**](examples/images) — showing how to use void (text-less) nodes to add images.
2016-06-28 16:00:05 -07:00
- [**Hovering menu**](examples/hovering-menu) — showing how a contextual hovering menu can be implemented.
- [**Tables**](examples/tables) — showing how to nest blocks to render more advanced components.
2016-07-06 15:13:15 -07:00
- [**Paste HTML**](examples/paste-html) — showing how to use an HTML serializer to handle pasted HTML.
- [**Code Highlighting**](examples/code-highlighting) — showing how to use decorators to dynamically mark text.
2016-06-28 09:27:00 -07:00
2016-06-28 15:53:10 -07:00
If you have an idea for an example that shows a common use case, pull request it!
2016-06-28 09:27:00 -07:00
2016-07-12 16:46:40 -07:00
<br/>
### Plugins
Slate encourages you to write small, reusable modules. Check out the list of public modules that you can use in your project!
- [**Plugins**](wiki#plugins)
- [**Serializers**](wiki#serializers)
2016-07-06 16:35:24 -07:00
<br/>
2016-07-06 16:35:45 -07:00
### Documentation
2016-06-28 09:35:51 -07:00
2016-07-08 12:32:49 -07:00
If you're using Slate for the first time, check out the [Getting Started](./docs/guides/installing-slate.md) guides and the [Core Concepts](./docs/concepts) to familiarize yourself with Slate's architecture and mental models. Once you've gotten familiar with those, you'll probably want to check out the full [API Reference](./docs/reference).
2016-06-28 15:53:10 -07:00
2016-07-11 12:34:22 -07:00
- [**Guides**](docs/guides)
2016-07-08 12:32:49 -07:00
- [Installing Slate](docs/guides/installing-slate.md)
- [Adding Event Handlers](docs/guides/adding-event-handlers.md)
2016-07-08 14:40:45 -07:00
- [Defining Custom Block Nodes](docs/guides/defining-custom-block-nodes.md)
- [Applying Custom Formatting](docs/guides/applying-custom-formatting.md)
- [Using Plugins](docs/guides/using-plugins.md)
2016-07-11 12:34:22 -07:00
- Saving to a Database
2016-07-06 16:38:58 -07:00
2016-07-11 12:34:22 -07:00
- **Concepts**
2016-07-06 16:50:45 -07:00
- Statelessness & Immutability
2016-07-11 12:34:22 -07:00
- The Document Model
2016-07-06 16:50:45 -07:00
- The Selection Model
- Plugins
2016-07-08 12:32:49 -07:00
- **Reference**
2016-07-06 16:50:45 -07:00
- Components
2016-07-11 16:06:33 -07:00
- [Editor](docs/reference/components/editor.md)
2016-07-11 18:55:26 -07:00
- [Placeholder](docs/reference/components/placeholder.md)
2016-07-06 16:50:45 -07:00
- Models
- Block
- Character
- Data
- Document
- Inline
- Mark
- Node
2016-07-11 16:06:33 -07:00
- [Selection](docs/reference/models/selection.md)
2016-07-06 16:50:45 -07:00
- State
- Text
- Transform
- Plugins
2016-07-12 11:17:59 -07:00
- [Plugins](docs/reference/plugins/plugins.md)
- [Core](docs/reference/plugins/core.md)
2016-07-06 16:27:37 -07:00
If even that's not enough, you can always [read the source itself](./lib), which is explained along with a handful of readme's.
2016-07-06 17:22:45 -07:00
<br/>
### License
The MIT License (MIT)
Copyright &copy; 2016, Ian Storm Taylor
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.