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/archbee.json b/archbee.json new file mode 100644 index 0000000000..ec73307cde --- /dev/null +++ b/archbee.json @@ -0,0 +1,324 @@ +{ + "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": "Introduction.md", + "children": [] + } + ] + }, + { + "categoryName": "Walkthroughs", + "isCategory": true, + "children": [ + { + "categoryName": "Installing Slate", + "isCategory": false, + "path": "walkthroughs/01-installing-slate.md", + "children": [] + }, + { + "categoryName": "Adding Event Handlers", + "isCategory": false, + "path": "walkthroughs/02-adding-event-handlers.md", + "children": [] + }, + { + "categoryName": "Defining Custom Elements", + "isCategory": false, + "path": "walkthroughs/03-defining-custom-elements.md", + "children": [] + }, + { + "categoryName": "Applying Custom Formatting", + "isCategory": false, + "path": "walkthroughs/04-applying-custom-formatting.md", + "children": [] + }, + { + "categoryName": "Executing Commands", + "isCategory": false, + "path": "walkthroughs/05-executing-commands.md", + "children": [] + }, + { + "categoryName": "Saving to a Database", + "isCategory": false, + "path": "walkthroughs/06-saving-to-a-database.md", + "children": [] + }, + { + "categoryName": "Using the Bundled Source", + "isCategory": false, + "path": "walkthroughs/xx-using-the-bundled-source.md", + "children": [] + } + ] + }, + { + "categoryName": "Concepts", + "isCategory": true, + "children": [ + { + "categoryName": "Interfaces", + "isCategory": false, + "path": "concepts/01-interfaces.md", + "children": [] + }, + { + "categoryName": "Nodes", + "isCategory": false, + "path": "concepts/02-nodes.md", + "children": [] + }, + { + "categoryName": "Locations", + "isCategory": false, + "path": "concepts/03-locations.md", + "children": [] + }, + { + "categoryName": "Transforms", + "isCategory": false, + "path": "concepts/04-transforms.md", + "children": [] + }, + { + "categoryName": "Operations", + "isCategory": false, + "path": "concepts/05-operations.md", + "children": [] + }, + { + "categoryName": "Commands", + "isCategory": false, + "path": "concepts/06-commands.md", + "children": [] + }, + { + "categoryName": "Editor", + "isCategory": false, + "path": "concepts/07-editor.md", + "children": [] + }, + { + "categoryName": "Plugins", + "isCategory": false, + "path": "concepts/08-plugins.md", + "children": [] + }, + { + "categoryName": "Rendering", + "isCategory": false, + "path": "concepts/09-rendering.md", + "children": [] + }, + { + "categoryName": "Serializing", + "isCategory": false, + "path": "concepts/10-serializing.md", + "children": [] + }, + { + "categoryName": "Normalizing", + "isCategory": false, + "path": "concepts/11-normalizing.md", + "children": [] + }, + { + "categoryName": "TypeScript", + "isCategory": false, + "path": "concepts/12-typescript.md", + "children": [] + }, + { + "categoryName": "Migrating", + "isCategory": false, + "path": "concepts/xx-migrating.md", + "children": [] + } + ] + }, + { + "categoryName": "API", + "isCategory": true, + "children": [ + { + "categoryName": "Transforms", + "isCategory": false, + "path": "api/transforms.md", + "children": [] + }, + { + "categoryName": "Node Types", + "isCategory": false, + "path": "api/nodes/README.md", + "children": [ + { + "categoryName": "Editor", + "isCategory": false, + "path": "api/nodes/editor.md", + "children": [] + }, + { + "categoryName": "Element", + "isCategory": false, + "path": "api/nodes/element.md", + "children": [] + }, + { + "categoryName": "Node", + "isCategory": false, + "path": "api/nodes/node.md", + "children": [] + }, + { + "categoryName": "NodeEntry", + "isCategory": false, + "path": "api/nodes/node-entry.md", + "children": [] + }, + { + "categoryName": "Text", + "isCategory": false, + "path": "api/nodes/text.md", + "children": [] + } + ] + }, + { + "categoryName": "Location Types", + "isCategory": false, + "path": "api/locations/README.md", + "children": [ + { + "categoryName": "Location", + "isCategory": false, + "path": "api/locations/location.md", + "children": [] + }, + { + "categoryName": "Path", + "isCategory": false, + "path": "api/locations/path.md", + "children": [] + }, + { + "categoryName": "PathRef", + "isCategory": false, + "path": "api/locations/path-ref.md", + "children": [] + }, + { + "categoryName": "Point", + "isCategory": false, + "path": "api/locations/point.md", + "children": [] + }, + { + "categoryName": "PointEntry", + "isCategory": false, + "path": "api/locations/point-entry.md", + "children": [] + }, + { + "categoryName": "PointRef", + "isCategory": false, + "path": "api/locations/point-ref.md", + "children": [] + }, + { + "categoryName": "Range", + "isCategory": false, + "path": "api/locations/range.md", + "children": [] + }, + { + "categoryName": "RangeRef", + "isCategory": false, + "path": "api/locations/range-ref.md", + "children": [] + }, + { + "categoryName": "Span", + "isCategory": false, + "path": "api/locations/span.md", + "children": [] + } + ] + }, + { + "categoryName": "Operation", + "isCategory": false, + "path": "api/operation.md", + "children": [] + } + ] + }, + { + "categoryName": "Libraries", + "isCategory": true, + "children": [ + { + "categoryName": "Slate React", + "isCategory": false, + "path": "libraries/slate-react.md", + "children": [] + }, + { + "categoryName": "Slate History", + "isCategory": false, + "path": "libraries/slate-history.md", + "children": [] + }, + { + "categoryName": "Slate Hyperscript", + "isCategory": false, + "path": "libraries/slate-hyperscript.md", + "children": [] + } + ] + }, + { + "categoryName": "General", + "isCategory": true, + "children": [ + { + "categoryName": "Resources", + "isCategory": false, + "path": "general/resources.md", + "children": [] + }, + { + "categoryName": "Contributing", + "isCategory": false, + "path": "general/contributing.md", + "children": [] + }, + { + "categoryName": "Changelog", + "isCategory": false, + "path": "general/changelog.md", + "children": [] + }, + { + "categoryName": "FAQ", + "isCategory": false, + "path": "general/faq.md", + "children": [] + } + ] + } + ] + } +} \ No newline at end of file diff --git a/docs/Introduction.md b/docs/Introduction.md index 7ddad6514f..2193c96fac 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -1,18 +1,29 @@ -# Introduction +--- +title: Introduction +docTags: +createdAt: Tue May 05 2026 15:31:37 GMT+0000 (Coordinated Universal Time) +updatedAt: Tue May 19 2026 16:52:42 GMT+0000 (Coordinated Universal Time) +--- -[Slate](http://slatejs.org) is a _completely_ customizable framework for building rich text editors. +[Slate](http://slatejs.org) is a *completely* customizable framework for building rich text editors. 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. +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/). + +This is my new line. + +:::BlockQuote +🤖 **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!\)_ +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... +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. @@ -30,9 +41,9 @@ Which brings me to how Slate solves all of that... ## Principles -Slate tries to solve the question of "[Why?](Introduction.md#why)" with a few principles: +Slate tries to solve the question of ":Link[Why?]{label="Why?" overridedLabel="Why?" spaceId docId="am6rx5ZLd6Yq0YpsN8fzx" version="v2" docAnchorId="#why" loadingMethod="dynamic" newTab="false" href="Introduction.md"}" 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. +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. @@ -42,21 +53,21 @@ Slate tries to solve the question of "[Why?](Introduction.md#why)" with a few pr ## Demo -Check out the [**live demo**](http://slatejs.org) of all of the examples! +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 `