plin2023 / blocksuite-chinese

🧩 BlockSuite is a framework for building collaborative editors and applications.

BlockSuite

---

Overview

BlockSuite is a toolkit for building collaborative editors and applications. It starts with a foundational block-based document model and independently implements a series of collaborative editing infrastructures, including editors. With BlockSuite, you can choose to:

• Build a new editor from scratch based on the BlockSuite framework.
• Or, reuse multiple first-party editors based on BlockSuite right out of the box:
  • DocEditor: Built entirely from scratch, DocEditor is a comprehensive block-based document editor, offering extensive customization and flexibility.
  • EdgelessEditor: Featuring canvas-based graphics rendering at its core with sophisticated rich-text features, EdgelessEditor offers unique functionalities and decent performance in whiteboard editing.

The BlockSuite project is structured around key packages that are categorized into two groups: a headless framework and prebuilt editing components.

Headless Framework
@blocksuite/store	Data layer for modeling collaborative document states. It is natively built on the CRDT library Yjs, powering all BlockSuite documents with built-in real-time collaboration and time-travel capabilities.
@blocksuite/inline	Minimal rich text components for inline editing. BlockSuite allows spliting rich text content in different block nodes into different inline editors, making complex content conveniently composable. This significantly reduces the complexity required to implement traditional rich text editing features.
@blocksuite/block-std	Framework-agnostic library for modeling editable blocks. Its capabilities cover the structure of block fields, events, selection, clipboard support, etc.
@blocksuite/lit	Intermediate layer for adapting the block tree to the lit framework component tree UI. BlockSuite uses lit as the default framework because lit components are native web components, avoiding synchronization issues between the component tree and DOM tree during complex editing.

Prebuilt Components
@blocksuite/blocks	Default block implementations for composing preset editors, including widgets belonging to each block.
@blocksuite/presets	Plug-and-play editable components including editors (DocEditor / EdgelessEditor) and auxiliary UI components named fragments (CopilotPanel, DocTitle...).

This can be illustrated as the diagram below:

In addition to extending custom blocks, here are what you can also conveniently achieve with BlockSuite:

• Writing type-safe complex editing logic based on the command mechanism, similar to react hooks designed for document editing.
• Persistence of documents and compatibility with various third-party formats (such as markdown and HTML) based on block snapshot and transformer.
• Incremental updates, real-time collaboration, local-first state management, and even decentralized data synchronization based on the document streaming mechanism of the document.
• State scheduling across multiple documents and reusing one document in multiple editors.

🚧 BlockSuite is currently in its early stage, with some extension capabilities still under refinement. Hope you can stay tuned, try it out, or share your feedback!

Getting Started

To try out BlockSuite, refer to the Quick Start document and start with the preset editors in @blocksuite/presets.

Resources

• 🎁 Examples
  • Nightly Playground
  • BlockSuite Monorepo in StackBlitz
  • Vue-based BlocksVite Editor
• 📝 Documentation
• 📍 Good First Issues
• 🎙️ GitHub Discussions
• 💬 Discord Channel
• 🚀 Releases

Building

See BUILDING.md for instructions on how to build BlockSuite from source code.

Contributing

BlockSuite accepts pull requests on GitHub. Before you start contributing, please make sure you have read and accepted our Contributor License Agreement. To indicate your agreement, simply edit this file and submit a pull request.

License

MPL 2.0