Blocks
Block kinds, nesting, void and island blocks, containers and layouts, default children, and the kind catalogue that powers menus and markdown shortcuts.
Every block has a kind, its type, and properties, its data (a heading’s level, a to-do’s checked: see Properties). Kinds come from plugins: each plugin’s blocks record declares the kinds it provides, how they render and how they behave structurally. This page covers the kinds that ship with Edytor and the structural rules every kind can opt into. To define your own, see Custom blocks.
Bundled kinds
<Edytor> includes createRichTextPlugin() by default. It provides:
| Type | Renders | data |
Notes |
|---|---|---|---|
paragraph |
div > p |
The default block type. | |
heading |
div > h1–h3 |
level: 'h1' | 'h2' | 'h3' |
Without a level, h1; any other level renders and copies as h3. Nested blocks render after the h1–h3, not inside it. |
bulleted-list-item |
li |
Continues on Enter. | |
numbered-list-item |
li |
Continues on Enter. | |
todo-item |
div with a checkbox |
checked: boolean |
Clicking the checkbox writes checked. Continues on Enter. |
toggle |
details |
Children form the collapsible body. Continues on Enter; a header over its children (container). Opens when created; an empty open one shows “Empty toggle. Click or drop blocks inside.” |
|
toggle-heading |
details > summary > h1–h3 |
level: 'h1' | 'h2' | 'h3' |
Notion’s toggle heading: a heading as a toggle’s header (container). |
callout |
div |
icon: string |
An icon (💡 by default, '' for none, picked by clicking it), a title (its text) and a content (its children, any blocks): Enter at the end of the title goes into the content (container, body). |
quote |
div > blockquote |
A header over its children (container), which render after the blockquote. |
|
divider |
hr |
Void, no content. Converting a block to it adds a paragraph after it for the caret. | |
ordered-list, unordered-list |
ol, ul |
Containers: children only, default child list-item. |
|
list-item |
li |
Continuing kinds and container headers are described in Enter and Backspace by role. Any block that shows its own text may hold color and background in its data, palette names the block menu sets and the core renders.
createImagePlugin(), which you list yourself, provides image, a void figure with an image from data.src and an editable caption (see Image).
createCodePlugin() provides code, an island whose children are codeLine blocks (default child codeLine), highlighted as you type.
createPagePlugin (opt-in) provides page, a void link to another document (data.pageId, data.title; see Page), and createTocPlugin() (opt-in) toc, a void listing the document’s headings (see Table of contents).
createColumnsPlugin() (opt-in) provides columns, a layout whose children are column blocks shown side by side, each holding any blocks (see Layouts and Columns).
Nesting
Any block can hold children unless its kind is void. Children render inside the parent, wherever the kind’s snippet places them.
In the editor:
- With
allowNestingset, Tab nests the current block under the block before it. Shift+Tab moves it out, after its parent; the blocks nested after it follow as its children, as in any outliner (an item of a list container leaves the list instead, see Containers). Over a selection of sibling blocks, both keys move them together and keep them selected. - Backspace at the start of a nested block that is its parent’s last child moves it out one level instead of merging (a heading, list item or other menu kind first turns into a paragraph; see Enter and Backspace by role).
- Block handles drag blocks before, after or inside other blocks, and, with the columns plugin, beside them (left or right, in columns).
edytor.moveandedytor.canMovedo the same from code (see Commands).
Deleting a block, or a block selection, does not delete the children that were not selected: they take the deleted block’s place. edytor.deleteBlocks(ids) with the ids of the whole subtree removes it all.
Void blocks
A void block (void: true) is a self-contained unit, such as a divider, an image or an embed. It is not part of the text flow:
- Its element is
contenteditable="false"; the editor does not edit its markup. Controls inside it (buttons, inputs) keep working. - It cannot receive children. Nothing can be inserted, moved or dropped into it. Turning a block with children into a void kind (
setBlockType,setBlock, a menu conversion) moves the children out, right after it; they take the default type of that slot when they came from an island.setBlockwithchildrenfor a void kind is refused. A child that still lands under it (a collaborator nests one at the same moment, orvalueplaces one there) is shown right after it instead (concurrent editing). - It never merges with a neighbor. Backspace at the start of the block after it selects the void block; a second Backspace deletes it.
- Slash commands and markdown shortcuts don’t convert it.
A void kind can still render its content. That text stays editable, which is how an image gets an editable caption.
Island blocks
An island (island: true) is editable inside but structurally sealed from the rest of the document. The code block is one: its lines are child blocks, but they belong to the code block only.
- Blocks inside an island cannot be moved, and nothing can be moved or dropped into it. The island itself moves as one block.
- Content never merges across its boundary. Backspace at the start of its first line does not join the line into the block before the island; with a single line, it selects the whole island.
- A range delete that starts inside an island never merges out of it.
- Extending a block selection with Shift+↑/↓ from outside never steps into an island’s inner blocks.
- Slash commands and markdown shortcuts don’t convert the island block itself.
- When an island is deleted, its children take its place and are converted to the default child type of their new parent. A line a collaborator adds to the island at the same time shows the same way; undoing the delete shows it as a line of the island again.
An island keeps whatever structure its interior builds: a table island of rows of cells, or a callout island holding a heading and nested paragraphs, keeps its kinds and nesting. An island that also declares lines: true is an island of lines, like the code block:
- Every direct child shows as the island’s
defaultChild(acodeLine) and holds no children, even when an undo or a collaborator’s edit puts another kind or a nested block there. A block nested under a line shows right after the island instead, and stays movable. - Inserting under a line is refused, and a block of the line kind outside such an island shows as its parent’s default child.
- The first line never merges into the island’s own content when the island renders none (
rendersContent: false).
The difference in one line: a void keeps the editor out, an island keeps the structure in.
These roles come from the plugins of the views attached to a document. A document edited with no view (a headless createDocument, a script) takes them from its semantics option instead, defaultSemantics (the bundled kinds) by default; add your own kinds with mergeSemantics (see Block roles). The server room applies defaultSemantics itself (see the room).
Containers
A kind that declares rendersContent: false has no text of its own. It only renders its children, like ordered-list, unordered-list, code, columns and column. The caret never lands in a container’s own slot. A list container that a deletion empties is removed.
A list holds only its items. Turn into converts the items a selection holds, never the list itself. Enter in an empty item outdents it, one level per press, until it ends the list. The keys at an item’s edges are listed in Enter and Backspace by role.
| When | What happens |
|---|---|
| An item is turned into another kind | It leaves the list, where Shift + Tab lifts it: before the list, after it, or between its two halves. Out of a list nested right in a list it leaves both. |
| An item is turned into the kind it already shows as (Numbered list in an ordered list) | It stays, and so does a block a merge left in the list turned into its own kind (Heading 2 on a heading). |
| Turn into adds a divider or a code block after an item with text | It goes after the item outside the list, which splits there. |
| A list is pasted into a list | A list of the list’s own kind (an <ol> into an ordered list) gives items; another kind keeps its kind. |
| The block between two halves of a split list goes | A list that a Turn into or an outdent split stays two lists: the second one’s numbering restarts, and its first item does not nest under the first list’s last item. Undo right after the split restores one list. |
List containers come from JSON, the API or a paste of an Edytor fragment. An HTML paste (from Google Docs, Word or a web page) gives flat bulleted and numbered items, as the lists you type (1. , - ) do, and flat items never split.
Layouts
A kind whose record says layout: true is a layout, like the columns plugin’s columns. Its defaultChild is its item kind (column), a container that holds any block; the layout shows its items side by side. A layout renders no content and holds only its items: nothing else moves or outdents directly into it, and no layout goes inside an item.
The document shows a layout by its role, on every replica, whatever a race stored:
- a block stored directly in a layout shows right after it;
- an item that shows no block does not show;
- a layout that shows one item, or none, shows as that item’s blocks;
- an item outside a layout shows as its blocks.
Edits write what those rules show: an item emptied by a delete, a merge or a move goes, and a layout left with one item is replaced by that item’s blocks, in the same undo step. Merges cross items in reading order: Backspace at the start of a column’s first block joins the previous column’s last line. A block selection holding every block of every item stands for the layout. See Columns for the gestures and the API.
Tables
A kind whose record says table: true is a table, like the table plugin’s table. Its defaultChild is its row kind (tableRow, a container), whose defaultChild is its cell kind (tableCell, an island holding text). The table lists its columns in data.columns, in order, and each cell names its column in data.column, so a column moves or goes by one write of that list.
The document shows a table by its role, on every replica, whatever a race stored:
- a row shows its cells in the table’s column order;
- a cell shows only in a row of a table, for a listed column, once (a cell an undo withdrew while it holds another person’s text still shows, its column after the listed ones);
- a row shows only in a table and while it shows a cell, a table while it shows a row;
- a row showing no cell for a column is padded there by the view, and the first edit there creates the cell.
A cell never moves, merges or splits: Enter in it is a line break and Backspace at its start does nothing. See Table for the gestures and the API.
Default children
When the editor creates a block next to the caret, the new block takes its parent’s default child type. This covers Enter at the start or end of a block, the second half of a block split with Enter, and the lines of an island that merges out. At the root, pressing Enter at the end of a heading or a quote therefore creates a paragraph; inside an ordered-list, it creates a list-item.
Continuing kinds (bulleted and numbered items, to-dos, toggles) continue themselves instead, and a block with both text and children keeps its kind when Enter splits it at its end: see Enter and Backspace by role.
Where the type comes from:
- A kind declares it with
defaultChild.ordered-listandunordered-listdeclarelist-item;codedeclarescodeLine;columnsdeclarescolumn. - Kinds without one, and the root, use the document’s default type,
paragraph. - Two plugins declaring different default children for the same kind is an error (
SemanticConflictError) when the editor starts.
Read the answer at runtime with edytor.defaultChild(parentBlock), which returns a type name.
Kinds and presets
A kind lists the ways to create it as presets. Each preset is a row in the kind catalogue, edytor.kinds, which the slash menu, the markdown shortcuts and your own block menus read:
edytor.kinds;
// [
// { id: 'block.paragraph', label: 'Text', icon: 'T', keywords: ['paragraph', 'plain'], value: { type: 'paragraph', data: {} }, replaces: false },
// { id: 'block.heading1', label: 'Heading 1', markdown: ['# '], value: { type: 'heading', data: { level: 'h1' } }, replaces: false },
// { id: 'block.heading2', label: 'Heading 2', … },
// { id: 'block.code', label: 'Code', markdown: ['```'], replaces: true, … },
// …
// ]
Each row has the preset’s label, icon, keywords, data, markdown prefixes and slash menu group, plus:
| Field | Meaning |
|---|---|
id |
The command id: block.<type>, numbered from 1 when a kind has several presets (block.heading2). |
value |
The conversion: type, the preset’s data, and the kind’s empty shape if it has one. |
replaces |
true when the kind has an empty shape (a divider, a code block). It converts in place only a block that holds nothing; a block with text or children stays intact and the new block is inserted after it. See presets. |
Convert a block with convertToKind, or run the row’s command by id:
import { convertToKind } from 'edytor';
const row = edytor.kinds.find((kind) => kind.id === 'block.quote');
const block = edytor.selection.caret?.block;
if (row) convertToKind(edytor, block, row); // true when it applied
await edytor.runCommand('block.heading2'); // converts the caret's block, or every selected or touched block
A kind’s command converts the caret’s block, every block of a block selection, or every block a text range touches that shows its own text (a closed toggle’s hidden body is not touched, and a list around the items stays a list), as one undo step. A replacing kind acts only on the block holding the selection’s start. See presets.
A “Turn into” menu that keeps the block’s text lists the rows with replaces: false:
{#each edytor.kinds.filter((kind) => !kind.replaces) as kind (kind.id)}
<button onclick={() => convertToKind(edytor, block, kind)}>{kind.icon} {kind.label}</button>
{/each}
Only convertible blocks convert: block.convertible is false for void blocks, islands and blocks inside an island.