Skip to main content

Core blocks

The core block library covers the typographic primitives every post / page needs: paragraphs, headings, lists, images, quotes, code, separators. They're registered into the editor unconditionally — neither plugins nor themes can disable them.

The blocks live in src/core/coreBlocks.ts and are registered via registerCoreBlock() (a variant of registerBlock that survives plugin disable/reset cycles).

Text blocks​

Paragraph​

The default block type. Hitting Enter at the end of any block creates a new paragraph below.

  • Inserter: Type / then "paragraph" or Enter on an empty line
  • Inspector: none — paragraphs have no special properties
  • Markdown round-trip: standard \n\n separator
  • Inline marks supported: bold, italic, underline, strike, inline code, link

Heading​

Headings H1 through H6. The block-level toolbar's level dropdown picks the level; each is rendered via the corresponding <h1>-<h6> tag.

  • Inserter: /heading then pick level (H1-H6 are separate inserter entries)
  • Inspector: level (H1-H6)
  • Markdown round-trip: # h1, ## h2, …, ###### h6
  • SEO note: typically the post title is the page's H1 (themes inject it). Use H2 onwards for body sections to avoid two H1s on the same page.

Bullet list / Ordered list​

Lists with arbitrary nesting. Tab to indent a list item; Shift+Tab to outdent.

  • Inserter: /bullet list or /ordered list
  • Markdown round-trip: standard -, 1.
  • Block toolbar acts on the entire list (not per-item) — to reorder items, drag them inside the list (Tiptap handles that).

Blockquote​

Indented quote block. Useful for testimonials, citations, callouts.

  • Inserter: /quote
  • Markdown round-trip: > prefixed lines
  • Inline marks supported: same as paragraph

Code block​

A monospaced fenced code block. Syntax highlighting is NOT done in the editor (would need a heavy dependency); themes can apply highlighter CSS post-publish if they want.

  • Inserter: /code
  • Inspector: language hint (used as the <code class="language-…">)
  • Markdown round-trip: triple-backtick fenced blocks with language hint

Horizontal rule​

A separator line. Visual break between sections.

  • Inserter: /separator or --- then Enter
  • Markdown round-trip: ---

Media blocks​

Image​

Insert an image from your media library OR from an external URL.

  • Inserter: /image
  • Inspector:
    • Media — opens the media picker; choose an existing image or upload a new one
    • From URL — paste an external image URL (no resize, browser loads directly)
    • Alt text — for screen readers + SEO
    • Caption — optional, surfaced by themes that render figure captions
    • Format — pick a variant (small / medium / large) — only when the image came from the library
    • Link to — none / media URL / custom URL
  • Markdown round-trip: ![alt](url) for plain images; figure markup for captioned images

Embed (the four built-in providers)​

YouTube, Vimeo, Twitter/X, Spotify. See Embeds for the full reference.

  • Inserter: /youtube, /vimeo, /twitter, /spotify
  • Inspector: paste a URL → the block parses it and stores the provider id
  • Markdown round-trip: <div data-cms-embed="<provider>" data-id="<x>" data-url="<y>"></div> markers

Layout blocks​

Custom HTML​

Paste raw HTML. Useful for:

  • Embedding code from third-party services that don't have a dedicated provider
  • Custom widgets (Stripe checkout buttons, Calendly, …)
  • Overriding default post layout for one specific post

See Custom HTML for the full reference.

Columns​

Multi-column layout primitive.

  • Inserter: /columns
  • Inspector: column count (2-6), per-column width ratio
  • Markdown round-trip: <div data-cms-block="core/columns"> marker; published HTML uses CSS grid

See Columns.

Theme blocks​

The active theme can register additional blocks that show up in the inserter under their theme namespace (e.g. magazine/hero-split, corporate/services-grid). See Theme blocks.

Inserter behaviour​

The / inserter (FloatingMenu in Tiptap parlance) appears when:

  • You hit / on an empty line
  • You click the + button in the gutter next to an empty paragraph

The list shows blocks grouped by category:

  • Text — paragraph, headings, lists, quote, code
  • Media — image, embed
  • Layout — columns, custom HTML
  • Embed — youtube, vimeo, twitter, spotify
  • Advanced — anything that doesn't fit elsewhere
  • Theme — blocks contributed by the active theme

Type to filter — /img highlights Image, /yt highlights YouTube. Enter inserts.

Block-level toolbar​

Each top-level block has a hover toolbar in its top-right corner with Move up / Move down / Duplicate / Delete. The toolbar acts on the depth-1 ancestor — if your cursor is in a list item, the toolbar reorders the entire list.

The toolbar's position is recomputed on every selectionUpdate / transaction so it tracks the active block as you type / scroll. mousedown.preventDefault() on the toolbar prevents the editor from blurring before the command dispatches.

Continue​