slate README

The project's README from github.com/ianstormtaylor/slate. As one markdown file: README.md.

A completely customizable framework
for building rich text editors.


Why? · Principles · Demo · Examples · Documentation · Contributing!



Slate lets you build rich, intuitive editors like those in Medium, Dropbox Paper or Google Docs—which are becoming table stakes for applications on the web—without your codebase getting mired in complexity.

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. It was inspired by libraries like Draft.js, Prosemirror and Quill.

🤖 Slate is currently in beta. Its core API is useable right now, but you might need to pull request improvements for advanced use cases, or fixes for some bugs. Some of its APIs are not "finalized" and will have breaking changes over time as we discover better solutions. There isn't currently a 1.0 release schedule, we're still getting the architecture right.

🤖 Slate is also contributor-driven. It is not backed by any huge company, which means that all contributions are voluntary and done by the people who need them. If you need something improved, added, or fixed, please contribute it yourself or no one will. And if you want to become a more active maintainer, let us know in the Slack channel.


Why?

Why create Slate? Well... (Beware: this section has a few of my opinions!)

Before creating Slate, I tried a lot of the other rich text libraries out there—Draft.js, Prosemirror, Quill, etc. What I found was that while getting simple examples to work was easy enough, once you started trying to build something like Medium, Dropbox Paper or Google Docs, you ran into deeper issues...

Of course not every editor exhibits all of these issues, but if you've tried using another editor you might have run into similar problems. To get around the limitations of their API's and achieve the user experience you're after, you have to resort to very hacky things. And some experiences are just plain impossible to achieve.

If that sounds familiar, you might like Slate.

Which brings me to how Slate solves all of that...


Principles

Slate tries to solve the question of "Why?" with a few principles:

  1. First-class plugins. The most important part of Slate is that plugins are first-class entities. That means you can completely customize the editing experience, to build complex editors like Medium's or Dropbox's, without having to fight against the library's assumptions.

  2. Schema-less core. Slate's core logic assumes very little 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 the most basic use cases.

  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 hierarchy.

  4. Parallel to the DOM. Slate's data model is based on the DOM—the document is a nested tree, it uses selections and ranges, and it exposes all the standard event handlers. This means that advanced behaviors like tables or nested block quotes are possible. Pretty much anything you can do in the DOM, you can do in Slate.

  5. Intuitive commands. Slate documents are edited using "commands", that are designed to be high-level and extremely intuitive to write and read, so that custom functionality is as expressive as possible. This greatly increases your ability to reason about your code.

  6. Collaboration-ready data model. The data model Slate uses—specifically how operations 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.

  7. Clear "core" boundaries. With a plugin-first architecture, and a schema-less core, it becomes a lot clearer where the boundary is between "core" and "custom", which means that the core experience doesn't get bogged down in edge cases.


Demo

Check out the live demo of all of the examples!


Examples

To get a sense for how you might use Slate, check out a few of the examples:

If you have an idea for an example that shows a common use case, pull request it!


Documentation

If you're using Slate for the first time, check out the Getting Started walkthroughs and the Concepts to familiarize yourself with Slate's architecture and mental models.

If even that's not enough, you can always read the source itself, which is heavily commented.

There are also translations of the documentation into other languages:

If you're maintaining a translation, feel free to pull request it here!


Packages

Slate's codebase is monorepo managed with Lerna. It consists of a handful of packages—although you won't always use all of them. They are:

Package Version Size Description
slate Slate's core data model logic.
slate-history A plugin that adds undo/redo history to Slate.
slate-hyperscript A hyperscript tool to write JSX Slate documents!
slate-react React components for rendering Slate editors.

Contributing!

All contributions are super welcome! Check out the Contributing instructions for more info!

Slate is MIT-licensed.

slate (ianstormtaylor/slate)

Searching Database…

31.7K ·GitHub
Slate
Что это такое?Полностью настраиваемый фреймворк для создания редакторов с форматированием текста в браузере — в духе Medium, Dropbox Paper или Google Docs — построенный как расширяемый contenteditable поверх React.
То есть это не готовый компонент редактора, который можно просто подключить?Это фреймворк, а не готовый редактор: вся логика живёт в плагинах, а ядро почти ничего не предполагает о схеме ваших данных, так что вы собираете нужный вам опыт редактирования, а не боретесь со встроенными допущениями.
Как добавить его в проект?Добавьте пакеты slate и slate-react в своё приложение, затем пройдите руководства Getting Started и документацию Concepts, чтобы разобраться в архитектуре и базовых моделях Slate.
Он привязывает меня к React?Да — он построен поверх React, а пакет slate-react поставляет React-компоненты, которые отрисовывают редактор, так что стек на React — фактически обязательное условие.
Он помечен как beta — насколько это рискованно, если я буду строить на нём проект уже сейчас?Основной API уже можно использовать, но часть API не финализирована и может измениться с нарушением совместимости, а графика релиза 1.0 нет. Проект развивается силами сообщества без поддержки какой-либо компании, так что исправления сложных случаев, возможно, лягут на вас.
Почему автор создал Slate, если Draft.js и ProseMirror уже существовали?Попробовав Draft.js, ProseMirror и Quill, он снова и снова упирался в одни и те же проблемы: жёстко зашитые схемы данных, запутанные программные преобразования, сериализацию как вспомогательную задачу, кастомные слои отображения и плоские модели документов, из-за которых таблицы и вставки превращались в боль.
Что умеют редакторы из примеров?В репозитории есть рабочие примеры: простой текст, форматированный текст, шорткаты в стиле Markdown, строчные узлы, картинки, всплывающая панель инструментов, таблицы, вставка HTML через HTML-сериализатор и @-упоминания — хороший обзор того, что покрывает система плагинов.
Как устроено представление документов внутри?Как вложенное рекурсивное дерево, аналогичное DOM: используются выделения и диапазоны, доступны стандартные обработчики событий, поэтому сложные структуры вроде таблиц и вложенных цитат поддерживаются на равных. Операции спроектированы так, чтобы поверх можно было добавить совместное редактирование.
Какие пакеты публикует монорепозиторий и за что каждый отвечает?Четыре: slate (логика основной модели данных), slate-react (React-компоненты для отрисовки), slate-history (плагин отмены и повтора действий) и slate-hyperscript (инструмент для записи документов Slate в JSX).
What are similar projects?ckeditor5, plate, lexical, tiptap, tinymce, BlockNote, pell, draft-js
Which topics is it in?contenteditable, rich-text, rich-text-editor, wysiwyg, text-editor, dom, collaboration, plugin-system, monorepo, editor, browser, plugin
Creator
ianstormtaylor
Size
28.9 MB
Stars
31.7K
Updated
CommitOct 18Release[email protected]Oct 18
Age
10y
Commits · 90 Days