Append Block
append_blockAppend blocks like headings, lists, tables, and embeds to AFFiNE documents with precise placement control and type validation.
Instructions
Append document blocks with canonical types and legacy aliases (supports placement + strict validation).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position on the edgeless canvas for frame/edgeless_text/note (default 0). Prefer ≥40px between sibling bounds; BlockSuite does not auto-arrange. | |
| y | No | Y position on the edgeless canvas for frame/edgeless_text/note (default 0). | |
| url | No | URL for bookmark/embeds | |
| html | No | Raw html for embed_html | |
| name | No | Attachment file name | |
| rows | No | Table row count | |
| size | No | Attachment/image file size in bytes | |
| text | No | Block content text | |
| type | Yes | Block type. Canonical: paragraph|heading|quote|list|code|divider|callout|latex|table|bookmark|image|attachment|embed_youtube|embed_github|embed_figma|embed_loom|embed_html|embed_linked_doc|embed_synced_doc|embed_iframe|database|data_view|surface_ref|frame|edgeless_text|note. Legacy aliases remain supported. | |
| docId | Yes | AFFiNE document id. | |
| embed | No | Attachment embed mode | |
| latex | No | Latex expression | |
| level | No | Heading level for type=heading | |
| style | No | List style for type=list | |
| width | No | Width for frame/edgeless_text/note. | |
| design | No | Design payload for embed_html | |
| height | No | Height for frame/edgeless_text/note. When `markdown` is set and height is omitted, an over-estimate is computed from the content — AFFiNE's render-time ResizeObserver corrects `prop:xywh` to the true DOM-measured height on first browser open. | |
| pageId | No | Target page/doc id for linked/synced doc embeds | |
| strict | No | Strict validation mode (default true) | |
| caption | No | Code caption when type is code | |
| checked | No | Todo state when type is todo | |
| columns | No | Table column count | |
| padding | No | Default padding (px) for `childElementIds` auto-sizing on frames (each side, plus +30px title band) and fallback gap for `stackAfter` (default 40). | |
| language | No | Code language when type is code | |
| markdown | No | When type='note', parse this markdown into heading/paragraph/list/code child blocks inside the note (BlockSuite-native: mirrors what happens when you paste markdown into an edgeless note). Takes precedence over 'text' for note children. Ignored for other block types. | |
| mimeType | No | Attachment mime type | |
| sourceId | No | Blob source id for image/attachment | |
| viewMode | No | Initial data view preset for type=database or type=data_view. Defaults: database=table, data_view=kanban | |
| iframeUrl | No | Override iframe src for embed_iframe | |
| placement | No | Optional insertion target/position | |
| reference | No | Target id for surface_ref | |
| background | No | Background for frame/note. Frame default 'transparent'. For notes, prefer AFFiNE's adaptive `--affine-note-background-<color>` family — `blue` / `purple` / `yellow` / `green` / `teal` / `red` / `orange` / `magenta` / `grey` / `white` / `black`. For specific per-theme colors, pass a `{light, dark}` hex object like `{light:'#fff', dark:'#252525'}`. | |
| refFlavour | No | Target flavour for surface_ref (e.g. affine:frame) | |
| stackAfter | No | Layout helper — position this block relative to one or more existing edgeless blocks. Picks the furthest anchor in `direction` for the stack axis, and centers the new block on the anchor group's union on the orthogonal axis (matches how BlockSuite aligns selection-derived blocks; reduces to inherit-anchor-x when widths match). Caller-provided x/y on the orthogonal axis still wins. Works for frame/note/edgeless_text. Example: `stackAfter: { blockId: [f1, f2, f3], gap: 80 }` stacks below whichever column frame ends lowest, centered across all three. Note heights shift at first render (page-root grows with the title, content notes shrink/grow with their children); give extra gap and fix up with `update_edgeless_block` if the down/right chain drifts. | |
| workspaceId | No | AFFiNE workspace id. Omit only when AFFINE_WORKSPACE_ID is configured. | |
| bookmarkStyle | No | Bookmark card style | |
| childElementIds | No | For type='frame' only. The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — BlockSuite's prop:childElementIds holds both, matching what the editor writes when you drag a note into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. When width/height are omitted the frame is sized to the union of resolvable child bounds + padding + a 30px title band. |