The block editor

Open any document in the admin and the block editor opens with it. A document is an ordered list of blocks. Each block is one piece of content — a paragraph, a heading, an image, a button — and you build a page by stacking and arranging them. There is no code to write and no markup to learn.

The block types

Cusp ships nine block types in the editor. Text-shaped blocks use TipTap for inline formatting; the rest are structured blocks with their own controls.

• Paragraph — body text. Supports the inline formatting toolbar and soft line breaks.
• Heading — a section title. Pick any level from H1 to H6; the document title renders separately, so body headings usually start at H2.
• List — a bulleted or numbered list. Items can nest to create sub-lists, and numbered lists can start at a chosen number.
• Quote — a blockquote with an optional citation line, and an optional callout style (note or warning) for admonitions.
• Image — a picture from your Media library. Upload a new file or pick an existing one, then set alt text, a caption, and alignment.
• Code — a verbatim code block with an optional language hint for syntax highlighting and an optional filename caption. Whitespace is preserved exactly.
• Button — a call-to-action link with a label, a destination, and a primary, secondary, or link style.
• Columns — a side-by-side layout of two to four columns, each holding its own blocks.
• Separator — a horizontal divider between sections.

Inside text blocks the inline formatting toolbar covers bold, italic, strikethrough, underline, inline code, and links. On the wire, rich text is stored as Portable Text, so the headless API hands every consumer a structured shape rather than a wall of HTML.

Add a block with the slash menu

The fastest way to add a block is the slash menu. On an empty line, type a slash to open it, then keep typing to filter — type "img" for image, "code" for code — and press Enter to insert the match. The menu lists block types in a fixed order with paragraph first.

Two block types ask a follow-up question before they insert. Heading prompts for a level, and columns prompts for how many columns to create. Pick the option and the block drops in at your cursor.

Columns and nesting

The columns block lays blocks out side by side. Each column is its own small stack of blocks, so you can put a paragraph next to an image, or two lists next to each other. You can adjust the relative width of each column and the gap between them.

Nesting is intentionally shallow: a column can hold ordinary blocks, but it cannot hold another columns block. When you open the slash menu inside a column, the columns option is hidden so the one-level rule cannot be broken by accident. This keeps every document walkable in a single flat pass for rendering and version diffs.

Real-time collaboration

Open the same document in two places and both editors connect to one shared session. You see who else is present, and when someone is working inside a block their name and colour appear on it so you know not to type over them. Edits broadcast to everyone immediately — there is no save button to coordinate around.

Edits are sent as block-level operations, not as a single saved blob, so two people editing different blocks both stick — and so do two people editing different fields of the same block, such as one changing alignment while another edits the text. Operations apply in the order they arrive at the session. Two people typing into the exact same paragraph fall back to last-write-wins, which is what the block-presence cue helps you avoid.

The shared session is a Cloudflare Durable Object, the DocumentSession. It serialises every operation, broadcasts to connected peers, tracks presence, and flushes to the database on idle or every 50 operations. There is no CRDT and no Yjs — the single-threaded actor model serialises writes for free.

Fields and blocks

The block editor handles a document's body, but a document is more than its body. Above the editor sits a form of typed fields defined by the document's content type — always a title and a slug, plus whatever the collection declares: a recipe's prep time, a page's hero image, a reference to another document. Blocks are free-form, ordered content; fields are structured, named values your theme and the headless API can read directly. Some field types hold repeating structured data — a recipe's ingredient list, for instance — which you edit row by row right on the form. The content types and fields guide covers how those fields are defined and what each type does.

Everything is versioned

Every change you make is captured in version history. You can browse earlier states of a document and restore any of them, and a restore is recorded as a new version rather than overwriting the past. Publishing pre-renders the page and serves it from Cloudflare's cache, while your drafts stay private until you are ready.

Adding an image inserts a file from your library. For how uploads work and which file types the image block accepts, see the media guide.