# typecellos/blocknote architecture

> Architecture diagram of the GitHub repository typecellos/blocknote, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/typecellos/blocknote
- Repository: https://github.com/typecellos/blocknote

## Overview

BlockNote is a React-based, block-oriented rich-text editor. An application creates an editor and renders it through a themed view; users edit structured blocks and inline content, with menus and controls exposing editing actions. The core also supports importing and exporting content, comments, collaboration, and version history, while optional packages add AI, diagram, and math features. The source index and excerpts show editor-to-block and React-controller relationships; several other capability links are documented by the README, but their internal wiring was not sampled.

Main entry points: [`packages/core/src/editor/BlockNoteEditor.ts`](https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/BlockNoteEditor.ts) (BlockNote editor), [`packages/core/src/blocks/defaultBlocks.ts`](https://github.com/typecellos/blocknote/blob/main/packages/core/src/blocks/defaultBlocks.ts) (Default block types), [`packages/core/src/editor/managers/BlockManager.ts`](https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/managers/BlockManager.ts) (Block operations), [`packages/mantine/src/BlockNoteView.tsx`](https://github.com/typecellos/blocknote/blob/main/packages/mantine/src/BlockNoteView.tsx) (Themed editor view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Editor core"]
  node_editor["BlockNote editor<br/>[BlockNoteEditor.ts]"]
  node_schema["Document schema<br/>[schema.ts]"]
  node_blocks["Default block types<br/>[defaultBlocks.ts]"]
  node_block_manager["Block operations<br/>[BlockManager.ts]"]
  node_block_commands["Block manipulation commands"]
  node_import_export["Content parsing and export"]
end

subgraph group_react["React interface"]
  node_react_api["React editor API"]
  node_view["Themed editor view<br/>[BlockNoteView.tsx]"]
  node_toolbar["Formatting and link toolbars"]
  node_suggestions["Suggestion menus"]
  node_table_ui["Table handles"]
end

subgraph group_collab["Collaboration and history"]
  node_comments["Comments<br/>[extension.ts]"]
  node_yjs["Yjs collaboration<br/>[YSync.ts]"]
  node_versioning["Version history<br/>[Versioning.ts]"]
end

subgraph group_extensions["Editor extensions"]
  node_extension_system["Extension system<br/>[index.ts]"]
end

subgraph group_addons["Optional features"]
  node_ai["AI editing"]
  node_diagram["Diagram blocks"]
  node_math["Math blocks"]
  node_export_addons["Extended export formats<br/>[docxExporter.ts]"]
end

node_user(("Application user"))

node_user -->|"edits in"| node_view
node_view -.->|"renders"| node_editor
node_react_api -->|"retrieves"| node_editor
node_editor -->|"configures"| node_blocks
node_blocks -->|"builds from"| node_schema
node_editor -->|"exposes"| node_block_manager
node_block_manager -->|"invokes"| node_block_commands
node_editor -->|"registers"| node_extension_system
node_editor -.->|"supports"| node_import_export
node_user -.->|"formats with"| node_toolbar
node_user -->|"chooses from"| node_suggestions
node_user -.->|"manipulates tables"| node_table_ui
node_editor -.->|"supports"| node_comments
node_editor -->|"collaborates through"| node_yjs
node_editor -.->|"supports"| node_versioning
node_editor -.->|"extends with"| node_ai
node_editor -.->|"embeds"| node_diagram
node_editor -.->|"embeds"| node_math
node_editor -.->|"exports through"| node_export_addons

click node_react_api "https://github.com/typecellos/blocknote/blob/main/packages/react/src/hooks/useBlockNoteEditor.ts"
click node_view "https://github.com/typecellos/blocknote/blob/main/packages/mantine/src/BlockNoteView.tsx"
click node_editor "https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/BlockNoteEditor.ts"
click node_schema "https://github.com/typecellos/blocknote/blob/main/packages/core/src/schema/schema.ts"
click node_blocks "https://github.com/typecellos/blocknote/blob/main/packages/core/src/blocks/defaultBlocks.ts"
click node_block_manager "https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/managers/BlockManager.ts"
click node_block_commands "https://github.com/typecellos/blocknote/tree/main/packages/core/src/api/blockManipulation/commands"
click node_import_export "https://github.com/typecellos/blocknote/tree/main/packages/core/src/api"
click node_toolbar "https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/LinkToolbar/LinkToolbarController.tsx"
click node_suggestions "https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/SuggestionMenu/SuggestionMenuController.tsx"
click node_table_ui "https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/TableHandles/TableHandlesController.tsx"
click node_comments "https://github.com/typecellos/blocknote/blob/main/packages/core/src/comments/extension.ts"
click node_yjs "https://github.com/typecellos/blocknote/blob/main/packages/core/src/y/extensions/YSync.ts"
click node_versioning "https://github.com/typecellos/blocknote/blob/main/packages/core/src/extensions/Versioning/Versioning.ts"
click node_extension_system "https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/managers/ExtensionManager/index.ts"
click node_ai "https://github.com/typecellos/blocknote/blob/main/packages/xl-ai/src/components/AIMenu/AIMenuController.tsx"
click node_diagram "https://github.com/typecellos/blocknote/blob/main/packages/diagram-block/src/block/helpers/render/DiagramBlockPreviewWithPopup.tsx"
click node_math "https://github.com/typecellos/blocknote/blob/main/packages/math-block/src/block/helpers/render/MathBlockPreviewWithPopup.tsx"
click node_export_addons "https://github.com/typecellos/blocknote/blob/main/packages/xl-docx-exporter/src/docx/docxExporter.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_schema,node_blocks,node_block_manager,node_block_commands,node_import_export,node_user toneBlue
class node_react_api,node_view,node_toolbar,node_suggestions,node_table_ui toneAmber
class node_comments,node_yjs,node_versioning toneMint
class node_extension_system toneRose
class node_ai,node_diagram,node_math,node_export_addons toneIndigo
```

## Components

### Editor core

- [BlockNote editor](https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/BlockNoteEditor.ts): `packages/core/src/editor/BlockNoteEditor.ts`
- [Document schema](https://github.com/typecellos/blocknote/blob/main/packages/core/src/schema/schema.ts): `packages/core/src/schema/schema.ts`
- [Default block types](https://github.com/typecellos/blocknote/blob/main/packages/core/src/blocks/defaultBlocks.ts): `packages/core/src/blocks/defaultBlocks.ts`
- [Block operations](https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/managers/BlockManager.ts): `packages/core/src/editor/managers/BlockManager.ts`
- [Block manipulation commands](https://github.com/typecellos/blocknote/tree/main/packages/core/src/api/blockManipulation/commands): `packages/core/src/api/blockManipulation/commands`
- [Content parsing and export](https://github.com/typecellos/blocknote/tree/main/packages/core/src/api): `packages/core/src/api`

### React interface

- [React editor API](https://github.com/typecellos/blocknote/blob/main/packages/react/src/hooks/useBlockNoteEditor.ts): `packages/react/src/hooks/useBlockNoteEditor.ts`
- [Themed editor view](https://github.com/typecellos/blocknote/blob/main/packages/mantine/src/BlockNoteView.tsx): `packages/mantine/src/BlockNoteView.tsx`
- [Formatting and link toolbars](https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/LinkToolbar/LinkToolbarController.tsx): `packages/react/src/components/LinkToolbar/LinkToolbarController.tsx`
- [Suggestion menus](https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/SuggestionMenu/SuggestionMenuController.tsx): `packages/react/src/components/SuggestionMenu/SuggestionMenuController.tsx`
- [Table handles](https://github.com/typecellos/blocknote/blob/main/packages/react/src/components/TableHandles/TableHandlesController.tsx): `packages/react/src/components/TableHandles/TableHandlesController.tsx`

### Collaboration and history

- [Comments](https://github.com/typecellos/blocknote/blob/main/packages/core/src/comments/extension.ts): `packages/core/src/comments/extension.ts`
- [Yjs collaboration](https://github.com/typecellos/blocknote/blob/main/packages/core/src/y/extensions/YSync.ts): `packages/core/src/y/extensions/YSync.ts`
- [Version history](https://github.com/typecellos/blocknote/blob/main/packages/core/src/extensions/Versioning/Versioning.ts): `packages/core/src/extensions/Versioning/Versioning.ts`

### Editor extensions

- [Extension system](https://github.com/typecellos/blocknote/blob/main/packages/core/src/editor/managers/ExtensionManager/index.ts): `packages/core/src/editor/managers/ExtensionManager/index.ts`

### Optional features

- [AI editing](https://github.com/typecellos/blocknote/blob/main/packages/xl-ai/src/components/AIMenu/AIMenuController.tsx): `packages/xl-ai/src/components/AIMenu/AIMenuController.tsx`
- [Diagram blocks](https://github.com/typecellos/blocknote/blob/main/packages/diagram-block/src/block/helpers/render/DiagramBlockPreviewWithPopup.tsx): `packages/diagram-block/src/block/helpers/render/DiagramBlockPreviewWithPopup.tsx`
- [Math blocks](https://github.com/typecellos/blocknote/blob/main/packages/math-block/src/block/helpers/render/MathBlockPreviewWithPopup.tsx): `packages/math-block/src/block/helpers/render/MathBlockPreviewWithPopup.tsx`
- [Extended export formats](https://github.com/typecellos/blocknote/blob/main/packages/xl-docx-exporter/src/docx/docxExporter.ts): `packages/xl-docx-exporter/src/docx/docxExporter.ts`

### Other components

- **Application user**

## Connections

- Application user → Themed editor view: edits in
- Themed editor view → BlockNote editor: renders
- React editor API → BlockNote editor: retrieves (evidence: `packages/react/src/hooks/useBlockNoteEditor.ts`)
- BlockNote editor → Default block types: configures (evidence: `packages/core/src/editor/BlockNoteEditor.ts`)
- Default block types → Document schema: builds from (evidence: `packages/core/src/blocks/defaultBlocks.ts`)
- BlockNote editor → Block operations: exposes (evidence: `packages/core/src/editor/BlockNoteEditor.ts`)
- Block operations → Block manipulation commands: invokes (evidence: `packages/core/src/editor/managers/BlockManager.ts`)
- BlockNote editor → Extension system: registers (evidence: `packages/core/src/editor/BlockNoteEditor.ts`)
- BlockNote editor → Content parsing and export: supports (evidence: `packages/core/src/editor/BlockNoteEditor.ts`)
- Application user → Formatting and link toolbars: formats with
- Application user → Suggestion menus: chooses from
- Application user → Table handles: manipulates tables
- BlockNote editor → Comments: supports
- BlockNote editor → Yjs collaboration: collaborates through
- BlockNote editor → Version history: supports
- BlockNote editor → AI editing: extends with
- BlockNote editor → Diagram blocks: embeds
- BlockNote editor → Math blocks: embeds
- BlockNote editor → Extended export formats: exports through
