docs: update per component intro (toeverything#6221)

packages/docs/.vitepress/sidebar.ts

@@ -129,12 +129,15 @@ export const components: DefaultTheme.NavItem[] = [
   {
     text: 'Editors',
     items: [
-      { text: '📝 DocEditor', link: 'components/editors/doc-editor' },
-      { text: '🎨 EdgelessEditor', link: 'components/editors/edgeless-editor' },
+      { text: '📝 Doc Editor', link: 'components/editors/doc-editor' },
+      {
+        text: '🎨 Edgeless Editor',
+        link: 'components/editors/edgeless-editor',
+      },
     ],
   },
   {
-    text: 'Blocks 🚧',
+    text: 'Blocks',
     items: [
       {
         text: 'Regular Blocks',
@@ -152,6 +155,7 @@ export const components: DefaultTheme.NavItem[] = [
             text: 'Attachment Block',
             link: 'components/blocks/attachment-block',
           },
+          { text: 'Divider Block', link: 'components/blocks/divider-block' },
         ],
       },
       {

packages/docs/components/blocks/attachment-block.md

@@ -1,5 +1,8 @@
 # Attachment Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to place attachment content. It supports optional style configurations to display as cards of different styles.
+
+## Reference
+
+- [`AttachmentBlockSchema`](/api/@blocksuite/blocks/variables/AttachmentBlockSchema.html)
+- [`AttachmentService`](/api/@blocksuite/blocks/classes/AttachmentService.html)

packages/docs/components/blocks/code-block.md

@@ -1,5 +1,7 @@
 # Code Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to display code snippets. The code highlighting of different languages can be set through the `language` field.
+
+## Reference
+
+- [`CodeBlockSchema`](/api/@blocksuite/blocks/variables/CodeBlockSchema.html)

packages/docs/components/blocks/database-block.md

@@ -1,5 +1,10 @@
 # Database Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to edit and display a data grid.
+
+In a database block, each row is a standard paragraph block or list block. It supports adding different types of columns to rows and displaying a kanban view based on column information.
+
+## Reference
+
+- [`DatabaseBlockSchema`](/api/@blocksuite/blocks/variables/DatabaseBlockSchema.html)
+- [`DatabaseService`](/api/@blocksuite/blocks/classes/DatabaseService.html)

packages/docs/components/blocks/divider-block.md

@@ -0,0 +1,7 @@
+# Divider Block
+
+This is a block used to display a divider line. It can be quickly obtained by typing `---` followed by pressing the space bar.
+
+## Reference
+
+- [`DividerBlockSchema`](/api/@blocksuite/blocks/variables/DividerBlockSchema.html)

packages/docs/components/blocks/embed-blocks.md

@@ -1,5 +1,11 @@
 # Embed Blocks
 
-::: info
-🚧 The comprehensive document of related components is still a work in progress.
-:::
+These are blocks used to embed complex external content. The BlockSuite framework allows for the quick creation of embed blocks through [embed helper](../../guide/working-with-block-tree#defining-new-blocks).
+
+Existing embed blocks that support BlockSuite document content include `EmbedLinkedDoc` and `EmbedSyncedDoc`, please refer to [link blocks](./link-blocks) for more details.
+
+## Reference
+
+- [`EmbedYoutubeBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedYoutubeBlockProps.html)
+- [`EmbedFigmaBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedFigmaBlockProps.html)
+- [`EmbedGithubBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedGithubBlockProps.html)

packages/docs/components/blocks/frame-block.md

@@ -1,5 +1,11 @@
 # Frame Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to mark a canvas area in the edgeless editor.
+
+When dragging the frame, the elements placed inside the frame move together with the frame. Note that there are no other blocks inside the frame. This association effect is based on the geometric area covered by the frame, not on a nested relationship at the model layer.
+
+In presentation mode, the viewport will be moved to focus the frames one after another.
+
+## Reference
+
+- [`FrameBlockSchema`](/api/@blocksuite/blocks/variables/FrameBlockSchema.html)

packages/docs/components/blocks/image-block.md

@@ -1,5 +1,8 @@
 # Image Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to display image content. It supports scaling in both the [doc editor](../editors/doc-editor) and the [edgeless editor](../editors/edgeless-editor), as well as an optional `caption`.
+
+## Reference
+
+- [`ImageBlockSchema`](/api/@blocksuite/blocks/variables/ImageBlockSchema.html)
+- [`ImageService`](/api/@blocksuite/blocks/classes/ImageService.html)

packages/docs/components/blocks/link-blocks.md

@@ -1,5 +1,13 @@
 # Link Blocks
 
-::: info
-🚧 The comprehensive document of related components is still a work in progress.
-:::
+These are blocks used to display link content in various ways.
+
+- The `Bookmark` block supports displaying general web content with optional style configurations to display as cards of different styles.
+- The `EmbedLinkedDoc` block supports embedding other BlockSuite documents as linked cards, also with various style configurations.
+- The `EmbedSyncedDoc` block supports embedding other BlockSuite documents as editable sub-documents, based on the first-party transclusion support provided by BlockSuite.
+
+## Reference
+
+- [`BookmarkBlockSchema`](/api/@blocksuite/blocks/variables/BookmarkBlockSchema.html)
+- [`BookmarkService`](/api/@blocksuite/blocks/classes/BookmarkService.html)
+- [`EmbedLinkedDocBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedLinkedDocBlockProps.html)

packages/docs/components/blocks/list-block.md

@@ -1,5 +1,12 @@
 # List Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to model list content with nesting support.
+
+- When the `type` of this block is `bulleted`, it displays as bulleted list items.
+- When the `type` of this block is `numbered`, it displays as numbered list items.
+- When the `type` of this block is `todo`, it displays as todo list items.
+
+## Reference
+
+- [`ListBlockSchema`](/api/@blocksuite/blocks/variables/ListBlockSchema.html)
+- [`ListService`](/api/@blocksuite/blocks/classes/ListService.html)

packages/docs/components/blocks/note-block.md

@@ -1,5 +1,14 @@
 # Note Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a container block used to place flowing document content.
+
+If a document is entirely edited within the [doc editor](../editors/doc-editor), then all of its text content will be placed in a single note block. However, in the [edgeless editor](../editors/edgeless-editor), it allows for placing multiple notes on the canvas, and also for splitting the content of a single note block into multiple different notes.
+
+In the doc editor, the display order of notes is determined by the arrangement order of the note block in the page block `children`. But in the edgeless editor, the position of the note block is determined by the `xywh` field, and its layering with other graphical content is determined by the `index` field. This allows it to be positioned on the whiteboard along with other graphical content.
+
+![block-nesting](../../images/block-nesting.png)
+
+## Reference
+
+- [`NoteBlockSchema`](/api/@blocksuite/blocks/variables/NoteBlockSchema.html)
+- [`NoteService`](/api/@blocksuite/blocks/classes/NoteService.html)

packages/docs/components/blocks/page-block.md

@@ -1,5 +1,13 @@
 # Page Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is the root node of the document tree, and its view implementation becomes the top-level UI of the editor.
+
+For instance, the [doc editor](../editors/doc-editor) and the [edgeless editor](../editors/edgeless-editor) implement two different views for the page block. Generally, content (leaf nodes) is not placed directly in the page block. Its direct children are usually at least one [note block](./note-block) and one optional [surface block](./surface-block). Rich text content like paragraphs and lists are generally placed in the note blocks, while graphical content is placed in the surface block.
+
+![block-nesting](../../images/block-nesting.png)
+
+## Reference
+
+- [`PageBlockSchema`](/api/@blocksuite/blocks/variables/PageBlockSchema.html)
+- [`DocPageService`](/api/@blocksuite/blocks/classes/DocPageService.html)
+- [`EdgelessPageService`](/api/@blocksuite/blocks/classes/EdgelessPageService.html)

packages/docs/components/blocks/paragraph-block.md

@@ -1,5 +1,14 @@
 # Paragraph Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a block used to place text content. It's generally placed inside a note block, but also supports nesting by pressing the tab key.
+
+- When the `type` value of this block is `text`, it displays as a sequence of texts.
+- When the `type` value of this block is `h1` / `h2` / `h3` / `h4` / `h5` / `h6`, it displays as titles of different levels.
+- When the `type` value of this block is `quote`, it displays as a quote.
+
+![block-nesting](../../images/block-nesting.png)
+
+## Reference
+
+- [`ParagraphBlockSchema`](/api/@blocksuite/blocks/variables/ParagraphBlockSchema.html)
+- [`ParagraphService`](/api/@blocksuite/blocks/classes/ParagraphService.html)

packages/docs/components/blocks/surface-block.md

@@ -1,5 +1,13 @@
 # Surface Block
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This is a container used to render graphical content.
+
+- In documents opened with the [edgeless editor](../editors/edgeless-editor), this block is required.
+- Its `elements` field can contain a large number of `CanvasElement`s. These elements use HTML5 canvas for rendering and can be interleaved with note blocks, with automatically flattening to use the fewest canvas contexts.
+
+![context-interleaving](../../images/context-interleaving.png)
+
+## Reference
+
+- [`SurfaceBlockSchema`](/api/@blocksuite/blocks/variables/SurfaceBlockSchema.html)
+- [`SurfaceService`](/api/@blocksuite/blocks/classes/SurfaceService.html)

packages/docs/components/editors/doc-editor.md

@@ -1,13 +1,51 @@
 # Doc Editor
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This editor component is designed for conventional flow content editing, offering functionalities aligned with rich text editors based on the frameworks like ProseMirror or Slate.
 
-This editor component is great at block-based rich text editng, with drag handle, slash menu, format toolbar and other built-in powerful widgets combined.
+<iframe src="https://try-blocksuite.vercel.app/starter/?init" frameborder="no" width="100%" height="500"></iframe>
+
+## Features
+
+- [Text](../blocks/paragraph-block), [lists](../blocks/list-block), and [code](../blocks/code-block) blocks, along with customizable inline elements.
+- [Images](../blocks/image-block), [attachments](../blocks/attachment-block), and customizable [embed](../blocks/embed-blocks) blocks.
+- [Database](../blocks/database-block) block that provides tables with kanban view support.
+- Bidirectional [links](../blocks/link-blocks) between documents and transclusion similar to Notion synced blocks.
+- Two types of selections, including native text selection and block-level selection.
+- Cross-block dragging and multiple widget toolbars.
+
+Moreover, this editor inherits capabilities built into the BlockSuite framework, including:
+
+- Per-user undo/redo stack
+- Real-time collaboration
+- [Document streaming](../../guide/data-synchronization#document-streaming)
+
+Notably, the BlockSuite framework allows runtime compatibility between the doc editor and the edgeless editor, beyond mere static file format compatibility. This means you can dynamically attach the same page object to different instances of the doc editor and edgeless editor.
+
+## Usage
 
 ```ts
 import { DocEditor } from '@blocksuite/presets';
+
+const editor = new DocEditor();
 ```
 
-<iframe src="https://try-blocksuite.vercel.app/starter/?init" frameborder="no" width="100%" height="500"></iframe>
+Assigning a [`page`](../../guide/working-with-block-tree#block-tree-basics) object to `editor.page` will attach a block tree to the editor, and [`editor.host`](../../guide/working-with-block-tree#block-tree-in-editor) contains the API surface for editing. The [quick start](../../guide/quick-start) guide also serves as an online playground.
+
+## Integration
+
+Like all BlockSuite editors, the editor UI is entirely composed of the combination of [block specs](../../guide/block-spec). A specialized [page block](../blocks/page-block) spec serves as the root node of the document and implements all top-level document UI, with main widgets also mounted on the page block. Accordingly, commonly used editing APIs are provided in the page service.
+
+To integrate and customize this editor, you can:
+
+- [Customize new block specs](../../guide/working-with-block-tree#defining-new-blocks)
+- 🚧 Configure widgets and customize new widgets
+- 🚧 Use UI components from any framework
+
+🚧 We are planning support for more frameworks.
+
+## Reference
+
+- [`DocEditor`](/api/@blocksuite/presets/classes/DocEditor.html)
+- [`DocPageService`](/api/@blocksuite/blocks/classes/DocPageService.html)
+
+Since `DocEditor` is a native web component, all DOM-related properties are inherited.

packages/docs/components/editors/edgeless-editor.md

@@ -1,13 +1,54 @@
 # Edgeless Editor
 
-::: info
-🚧 The comprehensive document of this component is still a work in progress.
-:::
+This editor component offers a canvas with infinite logical dimensions, suitable for whiteboard and graphic editing.
 
-This editor component is great at whiteboard graphics editing capabilites. It combines canvas-based graphics rendering and DOM-based block tree editing together. This facilitates both creative graphic design and structured document editing, catering to a wide range of user needs and workflows.
+<iframe src="https://try-blocksuite.vercel.app/starter/?init&mode=edgeless" frameborder="no" width="100%" height="500"></iframe>
+
+## Features
+
+- All the rich text editing capabilities in the [doc editor](./doc-editor).
+- `CanvasElement` rendered to HTML5 canvas, including shapes, brushes, connectors, and text.
+- Use of [frames](../blocks/frame-block) to denote canvas areas of any size.
+- Presentation mode achieved by switching between multiple frames in sequence.
+- Nestable group elements.
+- Various [link cards](../blocks/link-blocks) that can be inserted on top of the canvas.
+- Customizable toolbars and other widgets.
+
+Moreover, this editor inherits capabilities built into the BlockSuite framework, including:
+
+- Per-user undo/redo stack
+- Real-time collaboration
+- [Document streaming](../../guide/data-synchronization#document-streaming)
+
+Notably, the BlockSuite framework allows runtime compatibility between the doc editor and the edgeless editor, beyond mere static file format compatibility. This means you can dynamically attach the same page object to different instances of the doc editor and edgeless editor.
+
+## Usage
 
 ```ts
 import { EdgelessEditor } from '@blocksuite/presets';
+
+const editor = new EdgelessEditor();
 ```
 
-<iframe src="https://try-blocksuite.vercel.app/starter/?init&mode=edgeless" frameborder="no" width="100%" height="500"></iframe>
+## Integration
+
+Like all BlockSuite editors, the editor UI is entirely composed of the combination of [block specs](../../guide/block-spec). A specialized [page block](../blocks/page-block) spec serves as the root node of the document and implements all top-level document UI, with main widgets also mounted on the page block. Accordingly, commonly used editing APIs are provided in the page service.
+
+Specifically, the canvas element and some blocks that appear on the top layer of the canvas are located on the [surface block](../blocks/surface-block). Therefore, operating the edgeless editor also requires accessing the model and service mounted on this block.
+
+To integrate and customize this editor, you can:
+
+- [Customize new block specs](../../guide/working-with-block-tree#defining-new-blocks)
+- 🚧 Configure widgets and customize new widgets
+- 🚧 Use UI components from any framework
+
+🚧 We are planning support for more frameworks.
+
+## Reference
+
+- [`EdgelessEditor`](/api/@blocksuite/presets/classes/EdgelessEditor.html)
+- [`EdgelessPageService`](/api/@blocksuite/blocks/classes/EdgelessPageService.html)
+- [`SurfaceBlockModel`](/api/@blocksuite/blocks/classes/SurfaceBlockModel.html)
+- [`SurfaceService`](/api/@blocksuite/blocks/classes/SurfaceService.html)
+
+Since `EdgelessEditor` is a native web component, all DOM-related properties are inherited.

packages/docs/components/fragments/bi-directional-link-panel.md

@@ -1,5 +1,7 @@
 # Bi-Directional Link Panel
 
+This component is an external panel for visualizing the bi-directional links related to the document.
+
 ::: info
 🚧 The comprehensive document of this component is still a work in progress.
 :::

packages/docs/components/fragments/copilot-panel.md

@@ -1,5 +1,7 @@
 # Copilot Panel
 
+This component is an external panel for AI copilot.
+
 ::: info
 🚧 The comprehensive document of this component is still a work in progress.
 :::

packages/docs/components/fragments/doc-title.md

@@ -1,5 +1,9 @@
 # Doc Title
 
+This component is used for displaying an editable doc title.
+
+![](../../images/showcase-fragments-2.jpg)
+
 ::: info
 🚧 The comprehensive document of this component is still a work in progress.
 :::

packages/docs/components/fragments/frame-panel.md

@@ -1,5 +1,7 @@
 # Frame Panel
 
+This component is an external panel for visualizing the [frames](../blocks/frame-block) inside the [surface block](../blocks/surface-block).
+
 ::: info
 🚧 The comprehensive document of this component is still a work in progress.
 :::

packages/docs/components/fragments/outline-panel.md

@@ -1,5 +1,9 @@
 # Outline Panel
 
+This component is an external panel for visualizing the outline of the document.
+
+![](../../images/showcase-fragments-2.jpg)
+
 ::: info
 🚧 The comprehensive document of this component is still a work in progress.
 :::

packages/docs/components/overview.md

@@ -3,9 +3,9 @@
 In a nutshell, BlockSuite categorizes components into the following types:
 
 - **Editor** - A container used to present document content in various forms. Different editors are composed of different sets of [block specs](../guide/block-spec).
-- **Block** - The atomic unit for constructing document within the editor. Once a block spec is registered, multiple corresponding block instances can be rendered in the editor.
+- **Block** - The atomic unit for constructing document within the editor. Once a [block spec](../guide/block-spec) is registered, multiple corresponding block instances can be rendered in the editor.
 - **Widget** - Auxiliary components that contextually show up in the editor on demand, such as a search bar or color picker. Every block can define its own widgets.
-- **Fragment** - Independent components outside the editor. They share the document with the editor but have their own lifecycles.
+- **Fragment** - External components outside the editor. They share the document with the editor but have their own lifecycles.
 
 ![showcase-fragments-2](../images/showcase-fragments-2.jpg)
 

packages/docs/components/widgets/drag-handle.md

@@ -1,5 +1,7 @@
 # Drag Handle
 
+This widget is used for intuitive block-level dragging.
+
 ::: info
 🚧 The comprehensive document of related components is still a work in progress.
 :::