Skip to main content

Guides

Embedding

Block Reference

Clepit ships 12 built-in block types. Every block has a JSON shape, a renderer, and a programmatic insert path via editor.blocks.insert.

All blocks share the same envelope when serialised: id, type, data, and an optional tunes record.

The block shape

Every block serialises to the same JSON envelope. The id is assigned by the editor and can be omitted when constructing data programmatically.

JSON
{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

Highlighted call-out box with 4 variants.

FieldTypeRequiredDescription
htmlstringYesHTML content of the alert message. Inline tool markup is supported.
variant'error' | 'info' | 'success' | 'warning'YesVisual style of the alert. One of: error, info, success, warning.
JSON
{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

Audio block. Consumed via the audioUploader callback on Editor.create.

FieldTypeRequiredDescription
urlstringYesURL of the audio file to embed.
captionstringNoPlain-text caption displayed below the player.
altstringNoAccessible label for the audio element.
alignment'center' | 'left' | 'right'NoHorizontal alignment of the player. One of: center, left, right.
JSON
{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

Interactive checkbox list with per-item checked state.

FieldTypeRequiredDescription
itemsChecklistItem[]YesArray of checklist items, each with a text and checked state.
items[].textstringYesHTML content of the item label.
items[].checkedbooleanYesWhether the checkbox is checked.
JSON
{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

Syntax-highlighted code block. 50 languages are supported, including typescript, python, rust, go, ruby, swift and kotlin.

FieldTypeRequiredDescription
codestringYesThe raw code string to display.
languageCodeLanguageNoSyntax highlighting language. Defaults to typescript.
themeCodeThemeNoEditor colour theme. Defaults to github-dark.
showCopybooleanNoShow a copy button in the rendered output.
JSON
{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

delimiter

Visual separator between sections.

FieldTypeRequiredDescription
variant'line' | 'stars'YesVisual style of the divider. One of: line, stars.
JSON
{
  "type": "delimiter",
  "data": { "variant": "line" }
}

Top-level and section headings (h1 to h6). Inline tools work inside the html payload.

FieldTypeRequiredDescription
htmlstringYesHTML content of the heading. Inline tool markup is supported.
level'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'NoHeading level. One of: h1, h2, h3, h4, h5, h6. Defaults to h1.
JSON
{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

Image block with caption and alt text. Consumed via the imageUploader callback on Editor.create.

FieldTypeRequiredDescription
urlstringYesURL of the image to embed.
captionstringNoPlain-text caption displayed below the image.
altstringNoAlt text for the image element.
alignment'center' | 'left' | 'right'NoHorizontal alignment of the image. One of: center, left, right.
JSON
{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

list

Ordered or unordered list. Each item is html.

FieldTypeRequiredDescription
type'ordered' | 'unordered'YesList type. One of: ordered, unordered.
itemsstring[]YesArray of HTML strings, one per list item.
JSON
{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

paragraph

Rich-text paragraph. Accepts inline tool markup such as bold, italic, code, link, marker, and tooltip.

FieldTypeRequiredDescription
htmlstringYesHTML content of the paragraph. Inline tool markup is supported.
JSON
{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

Blockquote with an optional author attribution.

FieldTypeRequiredDescription
htmlstringYesHTML content of the quote body. Inline tool markup is supported.
authorstringNoPlain-text or HTML attribution shown beneath the quote.
JSON
{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

table

Data grid. First row can be used as a header; each cell is html.

FieldTypeRequiredDescription
datastring[][]YesTwo-dimensional array of HTML cell strings. The first row is the header row.
captionstringNoPlain-text or HTML caption displayed below the table.
showDownloadbooleanNoShow a download button in the rendered output.
JSON
{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

video

Video block. Consumed via the videoUploader callback on Editor.create.

FieldTypeRequiredDescription
urlstringYesURL of the video file or YouTube/Vimeo embed link.
captionstringNoPlain-text caption displayed below the player.
altstringNoAccessible label for the video element.
alignment'center' | 'left' | 'right'NoHorizontal alignment of the player. One of: center, left, right.
JSON
{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}