feat(docs): migrate bs docs

2026-09-03 07:10:46 +08:00 · 2026-04-29 17:23:23 +08:00
parent bf6fc66943
commit 0ccfacbc29
105 changed files with 5537 additions and 243 deletions
@@ -0,0 +1,8 @@
+# Attachment Block
+
+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)
+- [`AttachmentBlockService`](/api/@blocksuite/blocks/classes/AttachmentBlockService.html)
@@ -0,0 +1,7 @@
+# Code Block
+
+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)
@@ -0,0 +1,10 @@
+# Database Block
+
+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)
+- [`DatabaseBlockService`](/api/@blocksuite/blocks/classes/DatabaseBlockService.html)
@@ -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)
@@ -0,0 +1,11 @@
+# Embed Blocks
+
+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)
@@ -0,0 +1,11 @@
+# Frame Block
+
+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)
@@ -0,0 +1,8 @@
+# Image Block
+
+This is a block used to display image content. It supports scaling in both the [page editor](../editors/page-editor) and the [edgeless editor](../editors/edgeless-editor), as well as an optional `caption`.
+
+## Reference
+
+- [`ImageBlockSchema`](/api/@blocksuite/blocks/variables/ImageBlockSchema.html)
+- [`ImageBlockService`](/api/@blocksuite/blocks/classes/ImageBlockService.html)
@@ -0,0 +1,14 @@
+# Link Blocks
+
+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)
+- [`BookmarkBlockService`](/api/@blocksuite/blocks/classes/BookmarkBlockService.html)
+- [`EmbedLinkedDocBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedLinkedDocBlockProps.html)
+- [`EmbedSyncedDocBlockProps`](/api/@blocksuite/blocks/type-aliases/EmbedSyncedDocBlockProps.html)
@@ -0,0 +1,12 @@
+# List Block
+
+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)
+- [`ListBlockService`](/api/@blocksuite/blocks/classes/ListBlockService.html)
@@ -0,0 +1,14 @@
+# Note Block
+
+This is a container block used to place flowing document content.
+
+If a document is entirely edited within the [page editor](../editors/page-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 page editor, the display order of notes is determined by the arrangement order of the note block in the root 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)
+- [`NoteBlockService`](/api/@blocksuite/blocks/classes/NoteBlockService.html)
@@ -0,0 +1,14 @@
+# Paragraph Block
+
+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)
+- [`ParagraphBlockService`](/api/@blocksuite/blocks/classes/ParagraphBlockService.html)
@@ -0,0 +1,13 @@
+# Root Block
+
+This is the root node of the document tree, and its view implementation becomes the top-level UI of the editor.
+
+For instance, the [page editor](../editors/page-editor) and the [edgeless editor](../editors/edgeless-editor) implement two different views for the root block. Generally, content (leaf nodes) is not placed directly in the root 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
+
+- [`RootBlockSchema`](/api/@blocksuite/blocks/variables/RootBlockSchema.html)
+- [`PageRootService`](/api/@blocksuite/blocks/classes/PageRootService.html)
+- [`EdgelessRootService`](/api/@blocksuite/blocks/classes/EdgelessRootService.html)
@@ -0,0 +1,13 @@
+# Surface Block
+
+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)
+- [`SurfaceBlockService`](/api/@blocksuite/blocks/classes/SurfaceBlockService.html)