Skip to main content

Guides

Embedding

Core concepts

The block model

The heart of EditorData is the blocks array: Block objects that preserve order. Each Block carries its type, type-specific data, and optional tunes metadata.

FieldTypeDescription
idstring | undefinedOptional unique identifier, assigned by the editor at creation.
typeBlockToolTypeLiteral key that binds the block to its schema, input component, and renderer.
dataobjectType-specific data object: shape differs per block type.
tunesBlockTunes | undefinedOptional cross-type tune metadata dictionary. Key is the tune name, value is free-form data.
JSON
{
  "time": 1745000000000,
  "version": "1.0.0",
  "blocks": [
    {
      "id": "abc123",
      "type": "header",
      "data": { "html": "Hello world", "level": "h1" }
    },
    {
      "id": "def456",
      "type": "paragraph",
      "data": { "html": "This is a <b>rich</b> paragraph." }
    }
  ]
}

Block tools vs inline tools

Block tools create top-level slots directly inside EditorData. Inline tools decorate text inside the html payload a block contains. The two layers are entirely separate: they cannot be substituted for each other.

JSON-first output

The editor never persists HTML. When you call editor.data.extract(), you get pure EditorData JSON: complete including media URLs. This JSON can be stored in a database, personalised, or converted to other formats.

TypeScript
import { Editor } from '@clepit/core';

const editor = Editor.create({ containerId: 'editor' });

const data = editor.data.extract();
// data: EditorData
// {
//   time: 1745000000000,
//   version: '1.0.0',
//   blocks: [ ... ]
// }

Editor vs Renderer

Editor uses the browser DOM to let a user edit content (browser-only). Renderer takes previously saved EditorData and renders it as HTML (can run in the browser or via SSR).

Block tunes

Tunes are a type-agnostic metadata slot for any block type. The key is the tune name set by the system or a plugin, and the value is typed to BlockTuneData: any combination of string, number, boolean, or null. Tunes can add semantics without breaking the core data shape.

JSON
{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Some text." },
  "tunes": {
    "textAlign": { "alignment": "center" },
    "visibility": { "hidden": false }
  }
}