Block Types and Block Settings

A block is the unit the editor works in. Paragraphs, headings, alerts, tables, code blocks, images and tab groups are all blocks, and the editor moves, comments on, deletes and configures them one at a time. Every top-level block also carries a data-id that Leed assigns and maintains for you — you never type one, and you should never invent one — which is what lets an AI edit say “replace this block” and hit the right paragraph three revisions later.

Most of what makes blocks pleasant to work with is invisible until you move the pointer. Nothing below is discoverable by reading the toolbar.

flowchart LR
    INS["Between two blocks<br/>a plus button and a drop-cursor line<br/>inserts an empty paragraph"]
    LG["Left gutter<br/>Move up · Grab to drag · Move down<br/>top-level blocks only"]
    BLK["The block<br/>carries a data-id assigned by Leed"]
    PILL["Right pill<br/>Add comment · Add emoji comment · AI Assistant"]
    CHR["Widget chrome, top right<br/>settings gear · Delete block<br/>rich widgets only"]
    INS -.-> BLK
    LG --> BLK
    BLK --> PILL
    BLK --> CHR

The left hover gutter

Move the pointer into the left margin beside a block and three controls appear, anchored to that block: Move up, a grab handle, and Move down. The arrows move the block one position; the handle drags it anywhere in the document, with a line showing where it will land. Move up is absent on the first block and Move down on the last, so the cluster is two controls at the ends of a page and three in the middle.

Movement controls appear for top-level blocks only. A paragraph inside a list item, an alert or a tab panel is not a top-level block, so it has no mover — move the alert, not the paragraph inside it. To get a nested paragraph out of its container, use Ctrl + [ to lift it, then move it.

Hover between two blocks instead of beside one and you get the insert affordance: a plus button, with a horizontal line across the content column showing where the new block will go. Clicking it inserts an empty paragraph at that point — useful when two widgets are stacked against each other and there is no paragraph to click into.

The right hover pill

The right margin has its own hover cluster, and it is about people rather than structure: Add comment, Add emoji comment, and AI Assistant (Ctrl + J). Comments anchor to the block they were raised on and stay attached to it as the page changes around them — the whole story is on comments and reactions, and what the assistant can do from there is on AI help in the editor.

Selecting a whole block

Clicking inside a block puts a text cursor in it. Clicking its chrome — a code block’s header bar, a widget’s frame, the grab handle — selects the block itself as a single object. The difference matters: with the block selected, Backspace removes the whole thing rather than one character, and a drag moves the block rather than the text you highlighted.

Widget chrome: gear and delete

Every rich widget renders two controls at its top right: a settings gear that opens its dialog, and an ✕ button tooltipped Delete block. Both are hidden when the page is read-only, and the delete button is also hidden while you are in Viewing mode — that mode is deliberately incapable of changing anything.

Plain blocks — paragraphs, headings, blockquotes, lists — have no chrome at all. They are configured by the toolbar rather than by a dialog.

Every block settings dialog

Four of these are worth more than a table row.

Alert Settings

The gear on any alert opens Alert Settings, which has two fields and a Save.

Type is a dropdown of the five alert kinds, each shown with the icon it will carry on your site: Note, Tip, Info, Warning and Danger. Changing it repaints the widget immediately, so you can see the alert in its new color before saving.

Title is optional. Leave it blank and the published alert is headed with the capitalized type name — a warning alert reads Warning. Type something and that becomes the heading instead, which is how you get an alert headed Deleting a published page breaks every link to it rather than a generic Warning. A specific title is almost always worth writing: it is the line a reader scanning the page actually reads.

Collapse Settings

A collapsible block’s gear opens Collapse Settings: a Title — the line that stays visible when the block is shut — and a Collapsed by default checkbox. New blocks start open, so tick the box for anything you want folded away on arrival.

Code blocks

A code block has no gear. Its header bar carries the setting instead: a language button that reads Select Language until you choose, and then the language you chose. Any extra languages configured for your workspace in Settings → General are listed first, above the fourteen built in.

The block flips between two presentations on its own. With your cursor outside it, it shows the rendered result — syntax-highlighted code, the drawn Mermaid diagram, the typeset equation. Click into it and it becomes editable source. Move the cursor out and it renders again. There is no toggle to hunt for; the cursor is the toggle.

Mermaid diagrams and math blocks are the same block with the language pinned, which is why they behave identically. Instead of a language button their header is a link out to the reference you are most likely to want: Mermaid’s list of diagram types, and KaTeX’s list of supported functions. Both open in a new tab.

Tab groups

A tab group is a strip of tabs above a shared content area. The ＋ at the end of the strip adds a tab; each tab’s kebab menu offers Rename (which opens the Rename Tab dialog) and Delete; and the ✕ at the right of the header row deletes the whole group.

Two things constrain what you can do here.

The second is predefined groups. If your workspace has tab groups configured, the toolbar’s Tab Group button becomes a dropdown listing them alongside Custom Tab Group. Picking one builds the group with its tabs already named, in the configured order, and with the right code language pre-set on each tab where one is defined. A group built that way has no ＋ and no per-tab kebab — its roster is the configuration’s job, not the page’s, which is exactly what keeps the same tabs in the same order across every page that uses it. The reserved api-languages group is deliberately left out of that menu, because API pages generate it themselves.

Here is one, live, using this documentation set’s own operating-system group:

Pick a tab and every other operating-system tab group in this documentation set follows it, on this page and every other. That is the whole point of a predefined group, and it is also why groups are configured centrally rather than per page — a group whose tabs differ from page to page would send readers to the wrong one. Tab groups for consistent examples covers configuring them, and tabs covers the markup underneath.

Blocks with no settings

Paragraphs, headings, blockquotes, horizontal rules, bullet lists, ordered lists and task items have movement and comment affordances but no gear, because there is nothing to configure that the toolbar does not already do. A heading’s level is the block-type selector; a list’s type is the list buttons; a paragraph is a paragraph. If you are looking for a setting on one of these, it is on the editor toolbar reference — and if the control you want is missing from your toolbar entirely, it has been switched off for this page type, which what each page type lets you format explains.

Table blocks

Insert Table on the toolbar drops in a table with a header row. Everything after that happens through the Table Operations menu beside it, which appears when your cursor is in a table: insert a row above or below, insert a column left or right, merge cells, split a cell, and delete a row, a column or the whole table. Tab and Shift + Tab move between cells, which is much faster than clicking.

Two limits are worth knowing before you build something elaborate.

The data-id on every block

Every top-level block gets a data-id when it is created, and keeps it as the page is edited around it. You will never see it in the editor and you cannot set it. It matters for one reason: it is the anchor an AI edit uses. An MCP client reads your page’s markdown, finds the block it wants by its data-id, and asks Leed to insert before it, replace it or delete it — and because the id survives everything except deleting the block, that instruction is still correct after you have edited three paragraphs above it. Authoring pages over MCP covers the whole contract, including why a client should never invent one.