From c8090fc22a5ebabdbcb58b5feb5f7423d5ab8575 Mon Sep 17 00:00:00 2001 From: Archbee Date: Thu, 26 Mar 2026 11:21:32 +0000 Subject: [PATCH] Archbee draft docs --- .gitbook.json | 270 +++++++++++++++ .gitbook.yaml | 4 - .../archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx | 116 +++++++ .../archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx | 94 +++++ .../archbee-doc-F_wxmcpXXcFXBnlTLKotn.mdx | 325 ++++++++++++++++++ .../archbee-doc-Suu73rxKAwcxyuTwxwmYD.mdx | 161 +++++++++ .../archbee-doc-l5v_fYYYnHrwDlyHaXAXk.mdx | 229 ++++++++++++ .../archbee-doc-o9oX-ED5R9sJY9YsVYR-B.mdx | 57 +++ .../archbee-doc--sENpSlh53_q1Rw0Mi7Me.mdx | 17 + 9 files changed, 1269 insertions(+), 4 deletions(-) create mode 100644 .gitbook.json delete mode 100644 .gitbook.yaml create mode 100644 docs/Concepts/archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx create mode 100644 docs/Table of contents/archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx create mode 100644 docs/Walkthroughs/archbee-doc-F_wxmcpXXcFXBnlTLKotn.mdx create mode 100644 docs/Walkthroughs/archbee-doc-Suu73rxKAwcxyuTwxwmYD.mdx create mode 100644 docs/Walkthroughs/archbee-doc-l5v_fYYYnHrwDlyHaXAXk.mdx create mode 100644 docs/Walkthroughs/archbee-doc-o9oX-ED5R9sJY9YsVYR-B.mdx create mode 100644 docs/reusables/docRefs/archbee-doc--sENpSlh53_q1Rw0Mi7Me.mdx diff --git a/.gitbook.json b/.gitbook.json new file mode 100644 index 0000000000..8f1e2dcf51 --- /dev/null +++ b/.gitbook.json @@ -0,0 +1,270 @@ +{ + "docsPath": "docs/", + "structure": { + "readme": "Introduction.md", + "summary": "Summary.md", + "assets": ".gitbook/assets", + "docsTree": [ + { + "categoryName": "Table of contents", + "isCategory": true, + "children": [ + { + "categoryName": "Introduction", + "isCategory": false, + "path": "Table of contents/archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx", + "children": [] + } + ] + }, + { + "categoryName": "Walkthroughs", + "isCategory": true, + "children": [ + { + "categoryName": "Installing Slate", + "isCategory": false, + "path": "Walkthroughs/archbee-doc-F_wxmcpXXcFXBnlTLKotn.mdx", + "children": [] + }, + { + "categoryName": "Adding Event Handlers", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Defining Custom Elements", + "isCategory": false, + "path": "Walkthroughs/archbee-doc-l5v_fYYYnHrwDlyHaXAXk.mdx", + "children": [] + }, + { + "categoryName": "Applying Custom Formatting", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Executing Commands", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Saving to a Database", + "isCategory": false, + "path": "Walkthroughs/archbee-doc-Suu73rxKAwcxyuTwxwmYD.mdx", + "children": [] + }, + { + "categoryName": "Using the Bundled Source", + "isCategory": false, + "path": "Walkthroughs/archbee-doc-o9oX-ED5R9sJY9YsVYR-B.mdx", + "children": [] + } + ] + }, + { + "categoryName": "Concepts", + "isCategory": true, + "children": [ + { + "categoryName": "Interfaces", + "isCategory": false, + "path": "Concepts/archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx", + "children": [] + }, + { + "categoryName": "Nodes", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Locations", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Transforms", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Operations", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Commands", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Editor", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Plugins", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Rendering", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Serializing", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Normalizing", + "isCategory": false, + "children": [] + }, + { + "categoryName": "TypeScript", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Migrating", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "API", + "isCategory": true, + "children": [ + { + "categoryName": "Transforms", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Node Types", + "isCategory": false, + "children": [ + { + "categoryName": "Editor", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Element", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Node", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Text", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "Location Types", + "isCategory": false, + "children": [ + { + "categoryName": "Location", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Path", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Point", + "isCategory": false, + "children": [] + }, + { + "categoryName": "PointRef", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Range", + "isCategory": false, + "children": [] + }, + { + "categoryName": "RangeRef", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "Operation", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "Libraries", + "isCategory": true, + "children": [ + { + "categoryName": "Slate React", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Slate History", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Slate Hyperscript", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "General", + "isCategory": true, + "children": [ + { + "categoryName": "Resources", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Contributing", + "isCategory": false, + "children": [] + }, + { + "categoryName": "Changelog", + "isCategory": false, + "children": [] + }, + { + "categoryName": "FAQ", + "isCategory": false, + "children": [] + } + ] + }, + { + "categoryName": "Shadow Docs", + "isCategory": true, + "children": [], + "isShadowDocs": true + } + ] + } +} \ No newline at end of file diff --git a/.gitbook.yaml b/.gitbook.yaml deleted file mode 100644 index 0bd2f32f67..0000000000 --- a/.gitbook.yaml +++ /dev/null @@ -1,4 +0,0 @@ -root: ./docs -structure: - readme: Introduction.md - summary: Summary.md diff --git a/docs/Concepts/archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx b/docs/Concepts/archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx new file mode 100644 index 0000000000..0eecd40209 --- /dev/null +++ b/docs/Concepts/archbee-doc-exyXV6J_ffA0bpFGo8Amb.mdx @@ -0,0 +1,116 @@ +--- +title: Interfaces +slug: O-PT3Mj1g3mfkmk_Xuz1V +docTags: +createdAt: Wed May 08 2024 12:00:57 GMT+0000 (Coordinated Universal Time) +updatedAt: Thu Mar 26 2026 11:14:11 GMT+0000 (Coordinated Universal Time) +--- + +Slate works with pure JSON objects. All it requires is that those JSON objects conform to certain interfaces. For example, a text node in Slate must obey the `Text` interface: + +```typescript +interface Text { + text: string +} +``` + +Which means it must have a `text` property with a string of content. + +But **any** other custom properties are also allowed, and completely up to you. This lets you tailor your data to your specific domain and use case, adding whatever formatting logic you'd like, without Slate getting in the way. + +This interface-based approach separates Slate from most other richtext editors which require you to work with their hand-rolled "model" classes, and makes it much easier to reason about. It also means that it avoids startup time penalties related to "initializing" the data model. + +## Custom Properties + +To take another example, the `Element` node interface in Slate is: + +```typescript +interface Element { + children: Node[] +} +``` + +This is a very permissive interface. All it requires is that the `children` property be defined containing the element's child nodes. + +But you can extend elements (or any other interface) with your own custom properties that are specific to your domain. For example, you might have "paragraph" and "link" elements: + +```javascript +const paragraph = { + type: 'paragraph', + children: [...], +} + +const link = { + type: 'link', + url: 'https://example.com', + children: [...] +} +``` + +The `type` and `url` properties there are your own custom API. Slate sees that they exist, but it doesn't ever use them for anything. However, when it goes to render a link element you'll receive an object with the custom properties attached, so that you can render it as: + +```jsx +{element.children} +``` + +When getting started with Slate, it's important to understand all of the interfaces it defines. There are a handful of them that are discussed in each of the guides. + +## Helper Functions + +In addition to the typing information, each interface in Slate also exposes a series of helper functions that make them easier to work with. + +For example, when working with nodes: + +```javascript +import { Node } from 'slate' + +// Get the string content of an element node. +const string = Node.string(element) + +// Get the node at a specific path inside a root node. +const descendant = Node.get(value, path) +``` + +Or, when working with ranges: + +```javascript +import { Range } from 'slate' + +// Get the start and end points of a range in order. +const [start, end] = Range.edges(range) + +// Check if a range is collapsed to a single point. +if (Range.isCollapsed(range)) { + // ... +} +``` + +There are lots of helper functions available for all of the common use cases when working with the different interfaces. When getting started it pays to read through them all, because you can often simplify complex logic into just a handful of lines of code with them. + +## Custom Helpers + +In addition to the built-in helper functions, you might want to define your own custom helper functions and expose them on your own custom namespaces. + +For example, if your editor supports images, you might want a helper that determines if an element is an image element: + +```javascript +const isImageElement = element => { + return element.type === 'image' && typeof element.url === 'string' +} +``` + +You can define these as one-off functions easily. But you might also bundle them up into namespaces, just like the core interfaces do, and use them instead. For example: + +```javascript +import { Element } from 'slate' + +// You can use `MyElement` everywhere to have access to your extensions. +export const MyElement = { + ...Element, + isImageElement, + isParagraphElement, + isQuoteElement, +} +``` + +This makes it easy to reuse domain-specific logic alongside the built-in Slate helpers. diff --git a/docs/Table of contents/archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx b/docs/Table of contents/archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx new file mode 100644 index 0000000000..bb2ca23912 --- /dev/null +++ b/docs/Table of contents/archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx @@ -0,0 +1,94 @@ +--- +title: Introduction to Slate! +slug: AMvMrkw5HKGOZnpcwt0ym +docTags: +createdAt: Wed May 08 2024 12:00:57 GMT+0000 (Coordinated Universal Time) +updatedAt: Thu Mar 26 2026 11:14:11 GMT+0000 (Coordinated Universal Time) +--- + +[**Slate**](http://slatejs.org) is a *completely* customizable framework for building rich text editors. Testing again. + +Slate lets you build rich, intuitive editors like those in [**Medium**](https://medium.com/), [**Dropbox Paper**](https://www.dropbox.com/paper) or [**Google Docs**](https://www.google.com/docs/about/)—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**](https://facebook.github.io/react/). It was inspired by libraries like [**Draft.js**](https://facebook.github.io/draft-js/), [**Prosemirror**](http://prosemirror.net/) and [**Quill**](http://quilljs.com/). + +
+ 🤖 **Slate is currently in beta**. Its core API is usable now, but you might need to pull request fixes for advanced use cases. Some of its APIs are not "finalized" and will (breaking) change over time as we find better solutions. +
+ +## Why? + +Why create Slate? Well... *(Beware: this section has a few of* [**my**](https://github.com/ianstormtaylor) *opinions!)* + +Before creating Slate, I tried a lot of the other rich text libraries out there—[**Draft.js**](https://facebook.github.io/draft-js/), [**Prosemirror**](http://prosemirror.net/), [**Quill**](http://quilljs.com/), etc. What I found was that while getting simple examples to work was easy enough, once you started trying to build something like [**Medium**](https://medium.com/), [**Dropbox Paper**](https://www.dropbox.com/paper) or [**Google Docs**](https://www.google.com/docs/about/), you ran into deeper issues... + +- **The editor's "schema" was hardcoded and hard to customize.** Things like bold and italic were supported out of the box, but what about comments, or embeds, or even more domain-specific needs? +- **Transforming the documents programmatically was very convoluted.** Writing as a user may have worked, but making programmatic changes, which is critical for building advanced behaviors, was needlessly complex. +- **Serializing to HTML, Markdown, etc. seemed like an afterthought.** Simple things like transforming a document to HTML or Markdown involved writing lots of boilerplate code, for what seemed like very common use cases. +- **Re-inventing the view layer seemed inefficient and limiting.** Most editors rolled their own views, instead of using existing technologies like React, so you had to learn a whole new system with new "gotchas". +- **Collaborative editing wasn't designed for in advance.** Often the editor's internal representation of data made it impossible to use to for a realtime, collaborative editing use case without basically rewriting the editor. +- **The repositories were monolithic, not small and reusable.** The code bases for many of the editors often didn't expose the internal tooling that could have been re-used by developers, leading to having to reinvent the wheel. +- **Building complex, nested documents was impossible.** Many editors were designed around simplistic "flat" documents, making things like tables, embeds and captions difficult to reason about and sometimes impossible. + +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 APIs 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?**](archbee-doc-2LOSfUeifwus9N1mp1z3i.mdx)" 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**](http://slatejs.org) of all of the examples! + +## Examples + +To get a sense for how you might use Slate, check out a few of the examples: + +- [**Plain text**](https://www.slatejs.org/examples/plaintext) — showing the most basic case: a glorified `