docs: add component types page

README.md

@@ -27,7 +27,7 @@ BlockSuite is a toolkit for building collaborative editing applications. It embr
 
 In developing modern collaborative editing applications, the challenge lies not only in the internal implementation of the editor but also in the complex state management across many UI components. This means that the overall data flow of such applications should be consistently modeled and reused on a larger scale, reducing the interoperability cost between editor and non-editor components. **This is why BlockSuite completely separates the data model of collaborative content from the editor**. This allows any UI component, whether part of an editor or not, to simply **_attach_** to the same block tree document, **_composing_** a more flexible editing experience.
 
-![blocksuite-showcase-doc-edgeless-editors](./packages/docs/images/blocksuite-showcase-doc-edgeless-editors.jpg)
+![showcase-doc-edgeless-editors](./packages/docs/images/showcase-doc-edgeless-editors.jpg)
 
 Based on this concept, BlockSuite starts with a foundational block-based document model and independently implements a series of collaborative editing infrastructures, including editors. This means that with BlockSuite, you can choose to:
 
@@ -36,7 +36,7 @@ Based on this concept, BlockSuite starts with a foundational block-based documen
 
 The BlockSuite project is structured around key packages, as illustrated in the diagram below:
 
-![blocksuite-package-overview.png](./packages/docs/images/blocksuite-package-overview.png)
+![package-overview.png](./packages/docs/images/package-overview.png)
 
 These packages include:
 

packages/docs/.vitepress/config.ts

@@ -20,8 +20,8 @@ export default defineConfig({
       {
         text: 'Editors',
         items: [
-          { text: '🚧 DocEditor', link: '#' },
-          { text: '🚧 EdgelessEditor', link: '#' },
+          { text: '📝 DocEditor', link: '#' },
+          { text: '🎨 EdgelessEditor', link: '#' },
         ],
       },
       {
@@ -46,6 +46,7 @@ export default defineConfig({
       {
         text: 'Essentials',
         items: [
+          { text: 'Component Types', link: '/component-types' },
           { text: 'Block Basics', link: '/block-basics' },
           { text: 'Data Persistence', link: '/data-persistence' },
           { text: '🚧 Customize Blocks' },

packages/docs/blocksuite-overview.md

@@ -6,7 +6,7 @@ BlockSuite is a toolkit for building collaborative editing applications. It embr
 
 In developing modern collaborative editing applications, the challenge lies not only in the internal implementation of the editor but also in the complex state management across many UI components. This means that the overall data flow of such applications should be consistently modeled and reused on a larger scale, reducing the interoperability cost between editor and non-editor components. **This is why BlockSuite completely separates the data model of collaborative content from the editor**. This allows any UI component, whether part of an editor or not, to simply **_attach_** to the same block tree document, **_composing_** a more flexible editing experience.
 
-![blocksuite-showcase-doc-edgeless-editors](./images/blocksuite-showcase-doc-edgeless-editors.jpg)
+![showcase-doc-edgeless-editors](./images/showcase-doc-edgeless-editors.jpg)
 
 <!--
 > For an understanding of the design philosophy advocated by BlockSuite, please read the article "Editor-Agnostic, CRDT-Native".
@@ -19,7 +19,7 @@ Based on this concept, BlockSuite starts with a foundational block-based documen
 
 The BlockSuite project is structured around key packages, as illustrated in the diagram below:
 
-![blocksuite-package-overview.png](./images/blocksuite-package-overview.png)
+![package-overview.png](./images/package-overview.png)
 
 These packages include:
 

packages/docs/component-types.md

@@ -0,0 +1,25 @@
+# Component Types
+
+After getting started, this section outlines the foundational editing components in BlockSuite, namely `Editor`, `Fragment`, `Block` and `Widget`.
+
+![component-types](./images/component-types.png)
+
+## Editors and Fragments
+
+In BlockSuite, **_editors_** are not standalone entities but a composite of various editable blocks. The previously mentioned `@blocksuite/presets` includes reusable entities like `DocEditor` and `EdgelessEditor`. Besides these editors, BlockSuite also defines **_fragments_** - UI components that are not editors but are dependent on the document's state. These fragments, such as sidebars, panels, and toolbars, may be independent in lifecycle from the editors, yet integrate out-of-the-box when attached to the block tree.
+
+The distinction between editors and fragments lies in their complexity and functionality. **Fragments typically offer more simplified capabilities, serving specific UI purposes, whereas editors provide comprehensive editing capabilities over the block tree**. Nevertheless, both editors and fragments operate on similar technological stacks and data flows.
+
+![showcase-fragments](./images/showcase-fragments.jpg)
+
+## Blocks and Widgets
+
+To address the complexity and diversity of editing needs, BlockSuite architects its editors as assemblies of multiple editable blocks, termed [`BlockSpec`](./block-spec-apis)s. Each BlockSpec encapsulates the data schema, view, service, and logic required to compose the editor. These BlockSpecs collectively define the editable components within the editor's environment.
+
+BlockSuite encourages the derivation of various block spec implementations from a single block model to enrich the editing experience. For instance, the root node of the block tree, the page block, is implemented differently for `DocEditor` and `EdgelessEditor` through `DocPageBlockSpec` and `EdgelessPageBlockSpec`, respectively. These serve as the top-level UI components for their respective editors.
+
+Within each block spec, there can be widgets specific to that block's implementation, enhancing interactivity within the editor. BlockSuite leverages this widget mechanism to register dynamic UI components such as drag handles and slash menus within the doc editor.
+
+## Summary
+
+This document explains the interplay between editors, fragments, blocks, and widgets. The next sections will delve into more detailed functionalities of BlockSuite, starting with block tree manipulation.