DOCSEARCHbyAlgolia
Submit Docs

BlockSuite Documentation

repository·main·Indexed 26 days ago

https://github.com/toeverything/blocksuite

A toolkit and framework for building collaborative, block-based editors and multimodal applications. It provides a headless framework and a library of web components for rich-text, graphics, and complex document editing. Key components include @blocksuite/store for data management and reactivity, @blocksuite/std for core standard components and graphics (gfx) primitives, and extension managers for store and view-based customizations.

Tokens
120.2K
Snippets
178
Records
1K
Agent score
91%

What's inside BlockSuite

  1. Overview of BlockSuite

    main

    BlockSuite is a toolkit for building editors and collaborative applications. It provides a collection of content editing infrastructures, UI components, and editors. It can be used as a UI component library for building various editors or as a foundation to build new editors from scratch using its underlying vanilla framework.

    Key capabilities include:

    • Multimodal Content: Support for different view modes (text, slides, mind maps, etc.) using a consistent framework.
    • Complex Knowledge Management: Native state management across multiple documents to handle intertwined references.
    • Collaboration-Ready: Built-in real-time collaboration using CRDT technology for reliable data flow.

  4. Overview of BlockSuite Framework

    main

    BlockSuite is a toolkit for building editors and collaborative applications. It provides a series of content editing infrastructures, UI components, and editors. It can be used as a UI component library or as a minimized vanilla framework to build custom editors from scratch.

    Key capabilities include:

    • Reuse existing editors: Use PageEditor (block-based document editor) or EdgelessEditor (graphics editor with canvas support).
    • Framework-agnostic components: All components are native web components, allowing easy integration with React, Vue, or other frameworks.
    • Extensibility: Customize and enhance editors using a rich set of BlockSuite components.
    • Advanced Editing Features: Supports custom blocks, inline embeds, real-time collaboration via CRDT, type-safe command mechanisms, and document persistence (Markdown/HTML).

  5. Explore @blocksuite/std API index

    main

    The @blocksuite/std package provides core standard components for BlockSuite, including command management, lifecycle watching, and various extension interfaces for blocks, widgets, and configuration.

    Key classes available in this package include:

    • CommandManager: For managing user commands.
    • LifeCycleWatcher: For observing lifecycle events.

    Available extension functions include:

    • BlockViewExtension
    • ConfigExtensionFactory
    • FlavourExtension
    • KeymapExtension
    • WidgetViewExtension

  6. Core concepts of the BlockSuite document-centric approach

    main

    BlockSuite is built on a document-centric philosophy that separates the data layer from the rendering layer:

    • Separation of Data and Editor: Documents (doc objects) exist independently of the editor UI. This allows the same document to be used across different editor types (e.g., switching between a PageEditor and an EdgelessEditor whiteboard) while preserving operation history.
    • CRDT-Native: Uses CRDTs for real-time synchronization and conflict resolution in collaborative environments.
    • Fragments: Because the document is independent, you can build peripheral UI components (called fragments) that rely on the doc state but are not part of the main editor (e.g., an OutlineFragment for a sidebar).
    • Hybrid Rendering: Supports interleaving different rendering technologies. For example, standard text blocks can be rendered in the DOM, while graphic content can be rendered via HTML5 <canvas> for high performance, even with thousands of shapes.

  7. Understand the Root Block structure

    main

    The RootBlock is the top-level node of the document tree. It serves as the foundation for the editor's UI. In a standard document structure, content (leaf nodes) is not placed directly inside the RootBlock. Instead, the RootBlock typically contains:

    1. Note blocks: Used for rich text content like paragraphs and lists.
    2. Surface blocks: Used for graphical or canvas-based content.

    Different editor implementations (such as the Page Editor or Edgeless Editor) provide different view implementations for the same RootBlock.

  10. Understand the Edgeless Data Structure

    main

    In BlockSuite, edgeless mode documents are isomorphic to page mode documents. They are composed of blocks, and switching between modes does not require data conversion.

    In a standard rich text document, the root block typically contains a single Note Block which then contains paragraph blocks. In edgeless mode, the document can be split into multiple Note Blocks (note cards) that are positioned independently on a canvas.

    Typical Block Tree Structure (Edgeless):

    Root Block
  Surface Block
    Embed Block
    Shape Element
    Brush Element
  Note Block
    Paragraph Block 1
  Note Block
    Paragraph Block 2

  12. Explore BlockSuite via Playground Apps

    main

    The packages/playground/apps directory contains application entries used for the BlockSuite playground online site. These applications serve two primary purposes:

    1. Comprehensive Examples: They demonstrate the full capabilities of BlockSuite in a real-world application context.
    2. E2E Testing Entry Points: They act as the entry points for executing End-to-End (E2E) test cases.

    You can view the live playground at https://try-blocksuite.vercel.app.