The document. Written back on every change (unchanged blocks keep their objects); a document replaced from outside — a new array, not one changed in place — is loaded again, unless it equals the current one.
plugins
BlockPlugin[]
[]
The plugin blocks this editor can show and offer.
palette
string[]
every built-in block, then every plugin
The block types the slash menu offers, in this order (see below).
messages
Messages
—
UI text in the host's language: English text → translation.
inlinePlugins
InlinePlugin[]
—
Elements inside the text, such as a formula (see [[writing-plugins#inline-plugins
readonly
boolean
false
Shows the document without editing; plugin fields are hidden. A read-only editor never writes value.
placeholder
string
Write something, or press '/' for blocks…
The hint of an empty block.
nested
boolean
false
Set by plugins with nested blocks for their inner editor; a host never sets it.
An empty document is shown as one empty paragraph, so the value the editor writes back is never an empty array once it has been mounted: it is at least [{ type: 'md:p', indent: 0, text: '' }]. The preview skips empty paragraphs.
Preview props
Prop
Type
Default
Meaning
blocks
StoredBlock[]
—
The document to render.
plugins
BlockPlugin[]
—
The plugins whose previews render the plugin blocks.
messages
Messages
—
UI text in the host's language.
inlinePlugins
InlinePlugin[]
—
The same inline plugins as the editor's.
nested
boolean
false
Set by plugin previews that render their nested blocks.
The preview renders built-in blocks as plain HTML (p, h1…h6, ul/ol with nested items, blockquote, pre > code with a language-<lang> class, hr) and each plugin block with its plugin's preview. A block whose type has no plugin in plugins, or whose plugin has no preview, is not rendered.
Using Preview at all is your choice: the editor does not depend on it. An application with its own renderer can render the stored blocks itself, and its plugins can leave preview out.
messages given to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.
The palette
The palette is a list of palette ids: md:p, md:h1…md:h6, md:ul, md:ol, md:todo, md:quote, md:code, md:hr for the built-in blocks, and a plugin's type for a plugin. It decides:
which blocks the slash menu and the Turn-into menu offer, and in which order;
which markdown shortcuts work (typing ## turns a paragraph into a heading only if md:h2 is in the palette);
what pasted markdown may become: a pasted block of a type outside the palette becomes a paragraph, and a divider is dropped.
A plain paragraph (md:p) is always allowed as the fallback.
<script lang="ts">import { Editor, type StoredBlock } from'@atom-forge/brickee';
import { map, table, youtube } from'@atom-forge/brickee/plugins';
const plugins = [table, youtube, map];
// No h1 (the page title is one) and no code blocks.const palette = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
let value = $state<StoredBlock[]>([]);
</script><Editorbind:value{plugins}{palette} />
PALETTE_ITEMS lists the built-in blocks with their labels, hints and icons; BUILT_IN_IDS is just their ids in the default order.
Editing
Action
How
Insert a block
/ opens the slash menu (searchable by label, hint, keywords and their translations); the + button adds a block below.
Markdown shortcuts
At the start of a paragraph: # …###### , - / * / + , 1. , [] , > .
Inline formatting
Select text for the toolbar, or Ctrl/Cmd + B bold, I italic, U underline, Shift+X strikethrough, E code, K link, \ remove formatting. Subscript and superscript are on the toolbar. Typed markdown turns into its mark: **bold**, *italic* / _italic_, ~~strike~~ once a space, a punctuation mark or Enter follows; `code` and [text](url) on their closing character. Ctrl/Cmd+Z right after brings back the text as typed.
Indent
Tab / Shift+Tab (at most 6 levels).
Line break
Shift+Enter; in a code block Enter breaks the line and Shift+Enter or Ctrl/Cmd+Enter starts a new block.
Select blocks
Click (or tap) a block's handle, Esc in a block, Shift+↑/↓ past the edge of a block, or drag a text selection across blocks. Ctrl/Cmd+A in an empty block selects every block.
Move blocks
Drag the handle (also into and out of nested editors), Ctrl/Cmd+Shift+↑/↓, or Move up / Move down in the Turn-into menu (without dragging: touch screens, keyboard).
Turn into
Click the handle of a block or a selection for the Turn-into menu; from the keyboard / (or Ctrl/Cmd+/, the menu key, Shift+F10) on selected blocks, or Ctrl/Cmd+/ in a block's text. On a touch screen a tapped block shows its actions (add below, turn into, delete) beside its handle.
Copy, cut, paste
Copying selected blocks puts their markdown on the clipboard (plugin blocks through their markdown form) and, beside it, the blocks themselves (application/x-brickee+json). Formatted text from elsewhere (a web page, Google Docs, Word) keeps its headings, lists, tables and marks (fromHtml); plain text is read as markdown. Pasted into a Brickee editor, copied blocks come back as they were; a plugin block that editor does not offer (or a second unique one) falls back to its markdown form. Pasted anywhere else, the markdown arrives. Pasting while blocks are selected puts the blocks after them.
Paste
Multi-line text is read as markdown and becomes blocks.
Undo, redo
Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y.
What a block can turn into depends on what it holds (its content):
text blocks turn into each other and keep their formatting; turning text into code keeps only the letters;
a block without content (divider, video, map) only replaces empty blocks or other blocks without content;
a block with nested blocks (a box) can wrap the selected blocks, if it accepts all of them; Unwrap moves a box's blocks out; a box can turn into another box-like type, and the props with the same names carry over.
Scroll sync
A host that shows the editor and the preview side by side can make the preview follow the editor's scrolling. scrollSync() returns two Svelte actions and a function:
use:sync.source goes on the editor's scrolling box, use:sync.target on the preview's. The target is scrolled to the same fraction (0…1) of its scroll range as the source. The sync is one way: scrolling the preview moves nothing else.
It re-syncs once per animation frame when the source scrolls, and when the target box or its children change size. sync.align() re-syncs on demand, for example after the preview's width changed.
use:sync.target={on} takes a boolean (default true), for a host that switches the target between two boxes, such as a desktop pane and a phone frame: turn on the visible one.
The sync is proportional only: both boxes show roughly the same place, not exactly the same block. This is deliberate — it needs no markup and works with any preview.
scrollFraction(box) reads how far a box is scrolled (0…1; 0 when it does not scroll), and setScrollFraction(box, f) scrolls it there — for example to keep the place when the preview changes width while it is shown alone:
The editor and the preview
Editor props
valueStoredBlock[](bindable)[]pluginsBlockPlugin[][]palettestring[]messagesMessagesinlinePluginsInlinePlugin[]readonlybooleanfalsevalue.placeholderstringWrite something, or press '/' for blocks…nestedbooleanfalseAn empty document is shown as one empty paragraph, so the value the editor writes back is never an empty array once it has been mounted: it is at least
[{ type: 'md:p', indent: 0, text: '' }]. The preview skips empty paragraphs.Preview props
blocksStoredBlock[]pluginsBlockPlugin[]messagesMessagesinlinePluginsInlinePlugin[]nestedbooleanfalseThe preview renders built-in blocks as plain HTML (
p,h1…h6,ul/olwith nested items,blockquote,pre > codewith alanguage-<lang>class,hr) and each plugin block with its plugin'spreview. A block whose type has no plugin inplugins, or whose plugin has nopreview, is not rendered.Using
Previewat all is your choice: the editor does not depend on it. An application with its own renderer can render the stored blocks itself, and its plugins can leavepreviewout.messagesgiven to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.The palette
The
paletteis a list of palette ids:md:p,md:h1…md:h6,md:ul,md:ol,md:todo,md:quote,md:code,md:hrfor the built-in blocks, and a plugin'stypefor a plugin. It decides:##turns a paragraph into a heading only ifmd:h2is in the palette);A plain paragraph (
md:p) is always allowed as the fallback.<script lang="ts"> import { Editor, type StoredBlock } from '@atom-forge/brickee'; import { map, table, youtube } from '@atom-forge/brickee/plugins'; const plugins = [table, youtube, map]; // No h1 (the page title is one) and no code blocks. const palette = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)]; let value = $state<StoredBlock[]>([]); </script> <Editor bind:value {plugins} {palette} />PALETTE_ITEMSlists the built-in blocks with their labels, hints and icons;BUILT_IN_IDSis just their ids in the default order.Editing
/opens the slash menu (searchable by label, hint, keywords and their translations); the+button adds a block below.#…######,-/*/+,1.,[],>.Ctrl/Cmd+Bbold,Iitalic,Uunderline,Shift+Xstrikethrough,Ecode,Klink,\remove formatting. Subscript and superscript are on the toolbar. Typed markdown turns into its mark:**bold**,*italic*/_italic_,~~strike~~once a space, a punctuation mark orEnterfollows;`code`and[text](url)on their closing character.Ctrl/Cmd+Zright after brings back the text as typed.Tab/Shift+Tab(at most 6 levels).Shift+Enter; in a code blockEnterbreaks the line andShift+EnterorCtrl/Cmd+Enterstarts a new block.Escin a block,Shift+↑/↓past the edge of a block, or drag a text selection across blocks.Ctrl/Cmd+Ain an empty block selects every block.Ctrl/Cmd+Shift+↑/↓, or Move up / Move down in the Turn-into menu (without dragging: touch screens, keyboard)./(orCtrl/Cmd+/, the menu key,Shift+F10) on selected blocks, orCtrl/Cmd+/in a block's text. On a touch screen a tapped block shows its actions (add below, turn into, delete) beside its handle.application/x-brickee+json). Formatted text from elsewhere (a web page, Google Docs, Word) keeps its headings, lists, tables and marks (fromHtml); plain text is read as markdown. Pasted into a Brickee editor, copied blocks come back as they were; a plugin block that editor does not offer (or a second unique one) falls back to its markdown form. Pasted anywhere else, the markdown arrives. Pasting while blocks are selected puts the blocks after them.Ctrl/Cmd+Z,Ctrl/Cmd+Shift+ZorCtrl/Cmd+Y.What a block can turn into depends on what it holds (its
content):Scroll sync
A host that shows the editor and the preview side by side can make the preview follow the editor's scrolling.
scrollSync()returns two Svelte actions and a function:<script lang="ts"> import { Editor, Preview, scrollSync, type StoredBlock } from '@atom-forge/brickee'; import { PLUGINS } from '@atom-forge/brickee/plugins'; let value = $state<StoredBlock[]>([]); const sync = scrollSync(); </script> <div class="split"> <div class="pane" use:sync.source> <Editor bind:value plugins={PLUGINS} /> </div> <div class="pane" use:sync.target> <Preview blocks={value} plugins={PLUGINS} /> </div> </div> <style> .split { display: grid; grid-template-columns: 1fr 1fr; height: 100vh; } .pane { overflow-y: auto; } </style>use:sync.sourcegoes on the editor's scrolling box,use:sync.targeton the preview's. The target is scrolled to the same fraction (0…1) of its scroll range as the source. The sync is one way: scrolling the preview moves nothing else.sync.align()re-syncs on demand, for example after the preview's width changed.use:sync.target={on}takes a boolean (defaulttrue), for a host that switches the target between two boxes, such as a desktop pane and a phone frame: turn on the visible one.scrollFraction(box)reads how far a box is scrolled (0…1; 0 when it does not scroll), andsetScrollFraction(box, f)scrolls it there — for example to keep the place when the preview changes width while it is shown alone:import { scrollFraction, setScrollFraction } from '@atom-forge/brickee'; import { tick } from 'svelte'; export async function keepPlace(box: HTMLElement, change: () => void) { const f = scrollFraction(box); change(); // e.g. switch the preview width await tick(); setScrollFraction(box, f); }