A plugin is a BlockPlugin object plus two Svelte components: a view for the editor and a preview for the site. Everything a plugin needs is exported from @atom-forge/brickee — the bundled plugins use nothing else.
Anatomy
Member
Type
Meaning
type
string
The stored type. Must not start with md:; to pass the schema it must match ^[a-z][a-z0-9:-]{0,39}$.
label, hint
string
Name and short description in the slash and Turn-into menus.
keys
string
Extra search words for the slash menu.
icon
Icon
A @lucide/svelte icon component.
props
() => P
The props of a new block.
fields
PropField[]
The settings on the top of the block (optional).
form
Component<PluginFormProps>
The plugin's own form in the fields bar, below the fields (optional; see Custom fields form).
tag
(props: P) => string
The small label on the top of the block, before its fields. Parts separated by · are translated one by one.
content
'none' | 'text' | 'plain' | 'blocks'
What the block holds. Plugins use 'none' (props only) or 'blocks' (a nested document); it decides what Turn-into offers.
view
Component<PluginViewProps>
The block in the editor.
preview
Component<PluginPreviewProps>
The block on the site (optional). Without it, Preview renders nothing for the block — for apps that render stored blocks with their own renderer.
accepts
string[]
A container's allowed nested blocks, as palette ids; 'md:*' is every built-in block. Default: everything the host offers.
markdown
(props: P, ctx: MarkdownContext) => string
Its markdown form (optional).
unique
boolean
At most one per document, top level only.
P is the props type of the plugin; declare it as an interface extending Record<string, unknown>.
A plugin without content
A link button: a label, a link, a size and a colour — all set in fields, nothing typed into the block itself.
// safe-url.ts — only links the site should renderexportconstsafeUrl = (u: unknown) => {
const s = String(u ?? '').trim();
return/^(https?:|mailto:|\/(?!\/))/.test(s) ? s : '';
};
<!-- ButtonView.svelte: the block in the editor --><script lang="ts" module>export interface ButtonPropsextendsRecord<string, unknown> {
label: string;
url: string;
size: 'normal' | 'large';
color: string;
}
</script><script lang="ts">import { MousePointerClick } from'@lucide/svelte';
import { Empty, safeColor, type PluginViewProps } from'@atom-forge/brickee';
// Both bindable, even when the view does not use them: the editor binds them on every plugin view.let { props = $bindable(), blocks = $bindable() }: PluginViewProps<ButtonProps> = $props();
</script>{#if props.label}<spanclass="button"style:background={safeColor(props.color, '#2563eb')}>{props.label}</span>{:else}<Emptyicon={MousePointerClick}text="Set the label and the link above" />{/if}<style>.button {
display: inline-block;
padding: 0.5em1.2em;
border-radius: 8px;
color: #fff;
}
</style>
<!-- ButtonPreview.svelte: the block on the site --><script lang="ts">import { safeColor, type PluginPreviewProps } from'@atom-forge/brickee';
import type { ButtonProps } from'./ButtonView.svelte';
import { safeUrl } from'./safe-url';
let { props }: PluginPreviewProps<ButtonProps> = $props();
const href = $derived(safeUrl(props.url));
</script>{#if href && props.label}<p><aclass="button"class:large={props.size === 'large'}{href}style:background={safeColor(props.color, '#2563eb')}>{props.label}</a></p>{/if}
Each PropField is one setting on the top of the block. The editor draws them and stores their values in props.
Member
Meaning
key
The prop it edits.
label
Its label (translated through messages).
kind
text, textarea, color, select, slider or toggles.
placeholder
Hint of an empty text field; for an optional colour, the colour a click on "none" starts from.
options
{ value, label }[] for select, and for a slider that steps through values. An option label may use {n}, filled with its value. For toggles, { value, label, icon }[]: icon is the button, label its tooltip.
min, max, step, unit
A number slider: its range, step (default 1) and the unit shown after the value.
none
The label of the unset state: a number slider's notch left of min, or an optional colour's "none" button.
format
The field's text from the stored value (default: the value as a string).
parse
The stored value from the field's text (default: the text).
How each kind stores its value:
Kind
Stored value
text, textarea
The text, or what parse returns (parse: lines stores a list of lines).
select
The chosen option's value.
slider with options
The value of the option at the slider's position.
slider with min and max
The number as a string (for example '56'); the none notch removes the key.
color
A #rrggbb string; with none, clearing it removes the key.
toggles
The list of the options switched on, in options order ([] when none); the bundled table's header and footer are one.
An empty value ('', null or undefined, also when returned by parse) removes the key from props, so a preview must always handle a missing prop. A field's parse is also a good place to normalize input: the bundled YouTube field accepts any YouTube link and stores only the video id.
Custom fields form
The generated fields cover simple settings. For anything else — a picker of the app's own, values from the app's own data or context, a script — a plugin gives its own form: any Svelte component, shown in the block's fields bar below the fields (or alone, when the plugin has no fields).
The form receives PluginFormProps:
Prop
Meaning
props
The block's props (bindable). Assign a new object (props = { ...props, image: id }): that is one edit of the block, with its own undo step.
readonly
The editor is read-only. The fields bar, and with it the form, is not shown then.
The form is the app's code, so it takes its data wherever the app keeps it — its own modules, stores, or a Svelte context the app provides above the editor (plugin components are rendered beneath it). The editor knows nothing about it. A photo block, for example, stores the id of an image of the app's library and offers the images of the album the app names in a context of its own:
The host sets the album around the editor with provideAlbum(() => album). markdown runs outside components (copying blocks, toMarkdown), so it can use module data only, not a context. The stored id is a prop like any other, so it is untrusted: the view and the preview resolve it with the app's own lookup and render nothing for an unknown one.
The view
The view receives PluginViewProps:
Prop
Meaning
props
The block's props (bindable): a view may also edit them in place, as the table does.
blocks
The nested document (bindable); always [] for a plugin without content.
readonly
The editor is read-only.
palette, plugins
The host's palette (already narrowed to accepts) and plugins, for a nested editor.
Declare props and blocks with $bindable() even when the view does not use them. The fields are drawn above the view automatically; a view only has to show the block. Empty (props icon and text) is the dashed placeholder the bundled plugins show until their props are set; its text is translated.
The preview
The preview receives PluginPreviewProps: props, blocks and plugins. It is a plain Svelte component that renders the block for the site. UI text is available through useText (see Host contexts); anything else the app knows reaches it through the app's own modules and contexts.
Containers
A plugin with content: 'blocks' holds a nested document in blocks. Its view uses Frame, a thin box that draws the block's fields on its top and a nested editor below; its preview renders the inner blocks with a nested Preview.
Frame props: blocks (bindable), readonly, palette, plugins, and optionally placeholder for the nested editor. heading, empty and image (a URL) make a heading line, which is shown only when the fields are not (read-only mode or no fields).
How nesting works:
One level. A nested editor never offers blocks that hold blocks themselves, nor unique blocks. The schema rejects deeper documents.
accepts narrows what the nested editor offers to the listed palette ids, in the host's order. 'md:*' stands for every built-in block, so ['md:*', 'youtube'] is "text and videos". Without accepts, the nested editor offers everything the host does (minus containers and unique blocks).
The host's palette still applies: accepts can only narrow it, never add to it.
Wrapping blocks into a container from the Turn-into menu, and turning a container into another, is offered only when the container accepts every block going in.
blocksSchemaFor(plugins) checks accepts on the server (see On the server).
Unique blocks
unique: true — at most one per document, at the top level (a table of contents, for example). Once the document has one, the plugin leaves the slash and Turn-into menus, a second one pasted in falls back to its markdown form, and nested editors never offer it. The schema does not enforce it.
Markdown form
markdown(props, { inner }) returns the block as markdown, used when blocks are copied in the editor and by toMarkdown. inner is the nested blocks already as markdown ('' without any).
Return '' to leave the block out. Plugins whose output has no meaning as text (an ad slot, the bundled gap) simply have no markdown form. Three helpers keep the output well-formed:
Helper
Does
mdText(value)
Plain text made safe inside markdown: escapes inline marks and #, joins lines.
mdJoin(...parts)
Joins parts as separate blocks (blank line between), leaving out empty and falsy ones.
mdQuote(md)
Prefixes every line with > , for a box rendered as a blockquote.
Taking pasted tables
When markdown with a GFM table is pasted into the editor, or imported with fromMarkdown(text, { plugins }), the table goes to the first plugin that has fromTable. It gets the table and returns the new block's props:
interfaceMarkdownTable {
rows: string[][]; // the cells as inline markdown, row by row; the first row is the headeralign: ('left' | 'center' | 'right')[]; // per column, from the delimiter row (:--, :-:, --:)
}
fromTable?(table: MarkdownTable): P;
The bundled table has it (fromTable: ({ rows, align }) => ({ rows, heads: ['top'], align })), so a table pasted into an editor that offers it becomes a table block. Without such a plugin the table stays text.
Inline plugins
An inline plugin is an element inside a block's text — a formula, a mention, a variable — that moves and deletes as one, while the stored text stays inline markdown. Give the same list to the editor and the preview (inlinePlugins); nested editors and plugin views (a table's cells) get it through a context (useInlinePlugins()).
interfaceInlinePlugin<D extendsRecord<string, string>> {
type: string; label: string; icon: Icon;
pattern: RegExp; // its markdown form in the text (global, bounded)parse(match: string[]): D; // a match → the datamarkdown(data: D): string; // the data → its markdown form (parse of it gives the same data)render(data: D): string; // the data → safe HTML (escape what comes from the data)fields: PropField[]; // edited in a popup when the element is clickedcreate(text: string): D; // a new one from the selected or typed texttyping?: { open: string; close: string }; // typing open…close and a space makes one
}
How it works: inline() looks for the patterns outside code spans and escaped characters, and puts render's HTML in a span that carries the markdown form (data-md); the editor's span is not editable text. Converting back to markdown takes the data-md, so a document saves the same even where the plugin is missing (its markdown form then shows as text). The toolbar gets a button per inline plugin, a click on an element opens its fields, and typing works like **bold**. inlineMath in @atom-forge/brickee/math is the bundled example.
Taking files
When files are pasted into the editor (a copied image, a screenshot) or dropped on it from outside the page, the first plugin the editor offers that has fromFiles and returns props gets one block of its own:
fromFiles?(files: File[]): P | null | Promise<P | null>;
Return null to leave the files to the next plugin. Uploading and storing them is the plugin's business, so it may return a promise — upload, then return the props with the stored URL or id. A pasted file goes after the block with the caret (or in place of an empty one); a dropped one where the drop line shows.
Writing plugins
A plugin is a
BlockPluginobject plus two Svelte components: a view for the editor and a preview for the site. Everything a plugin needs is exported from@atom-forge/brickee— the bundled plugins use nothing else.Anatomy
typestringtype. Must not start withmd:; to pass the schema it must match^[a-z][a-z0-9:-]{0,39}$.label,hintstringkeysstringiconIcon@lucide/svelteicon component.props() => PfieldsPropField[]formComponent<PluginFormProps>tag(props: P) => string·are translated one by one.content'none' | 'text' | 'plain' | 'blocks''none'(props only) or'blocks'(a nested document); it decides what Turn-into offers.viewComponent<PluginViewProps>previewComponent<PluginPreviewProps>Previewrenders nothing for the block — for apps that render stored blocks with their own renderer.acceptsstring[]'md:*'is every built-in block. Default: everything the host offers.markdown(props: P, ctx: MarkdownContext) => stringuniquebooleanPis the props type of the plugin; declare it as an interface extendingRecord<string, unknown>.A plugin without content
A link button: a label, a link, a size and a colour — all set in fields, nothing typed into the block itself.
// safe-url.ts — only links the site should render export const safeUrl = (u: unknown) => { const s = String(u ?? '').trim(); return /^(https?:|mailto:|\/(?!\/))/.test(s) ? s : ''; };<!-- ButtonView.svelte: the block in the editor --> <script lang="ts" module> export interface ButtonProps extends Record<string, unknown> { label: string; url: string; size: 'normal' | 'large'; color: string; } </script> <script lang="ts"> import { MousePointerClick } from '@lucide/svelte'; import { Empty, safeColor, type PluginViewProps } from '@atom-forge/brickee'; // Both bindable, even when the view does not use them: the editor binds them on every plugin view. let { props = $bindable(), blocks = $bindable() }: PluginViewProps<ButtonProps> = $props(); </script> {#if props.label} <span class="button" style:background={safeColor(props.color, '#2563eb')}>{props.label}</span> {:else} <Empty icon={MousePointerClick} text="Set the label and the link above" /> {/if} <style> .button { display: inline-block; padding: 0.5em 1.2em; border-radius: 8px; color: #fff; } </style><!-- ButtonPreview.svelte: the block on the site --> <script lang="ts"> import { safeColor, type PluginPreviewProps } from '@atom-forge/brickee'; import type { ButtonProps } from './ButtonView.svelte'; import { safeUrl } from './safe-url'; let { props }: PluginPreviewProps<ButtonProps> = $props(); const href = $derived(safeUrl(props.url)); </script> {#if href && props.label} <p> <a class="button" class:large={props.size === 'large'} {href} style:background={safeColor(props.color, '#2563eb')}> {props.label} </a> </p> {/if}// button.ts: the plugin import { MousePointerClick } from '@lucide/svelte'; import { mdText, type BlockPlugin } from '@atom-forge/brickee'; import ButtonView, { type ButtonProps } from './ButtonView.svelte'; import ButtonPreview from './ButtonPreview.svelte'; import { safeUrl } from './safe-url'; export const button: BlockPlugin<ButtonProps> = { type: 'button', label: 'Button', hint: 'A link as a button', keys: 'button link cta', icon: MousePointerClick, props: () => ({ label: '', url: '', size: 'normal', color: '#2563eb' }), fields: [ { key: 'label', label: 'Label', kind: 'text' }, { key: 'url', label: 'Link', kind: 'text', placeholder: 'https://…', parse: (s) => s.trim() }, { key: 'size', label: 'Size', kind: 'select', options: [ { value: 'normal', label: 'Normal' }, { value: 'large', label: 'Large' } ] }, { key: 'color', label: 'Colour', kind: 'color' } ], tag: (p) => (p.size === 'large' ? 'button · large' : 'button'), content: 'none', markdown: (p) => { const href = safeUrl(p.url); return href ? `[${mdText(p.label) || href}](${href})` : ''; }, view: ButtonView, preview: ButtonPreview };Register it beside the others:
<Editor bind:value plugins={[...PLUGINS, button]} /> <Preview blocks={value} plugins={[...PLUGINS, button]} />Fields
Each
PropFieldis one setting on the top of the block. The editor draws them and stores their values inprops.keylabelmessages).kindtext,textarea,color,select,sliderortoggles.placeholderoptions{ value, label }[]forselect, and for asliderthat steps through values. An option label may use{n}, filled with its value. Fortoggles,{ value, label, icon }[]:iconis the button,labelits tooltip.min,max,step,unitslider: its range, step (default 1) and the unit shown after the value.nonemin, or an optional colour's "none" button.formatparseHow each kind stores its value:
text,textareaparsereturns (parse: linesstores a list of lines).selectvalue.sliderwithoptionssliderwithminandmax'56'); thenonenotch removes the key.color#rrggbbstring; withnone, clearing it removes the key.togglesoptionsorder ([]when none); the bundled table's header and footer are one.An empty value (
'',nullorundefined, also when returned byparse) removes the key fromprops, so a preview must always handle a missing prop. A field'sparseis also a good place to normalize input: the bundled YouTube field accepts any YouTube link and stores only the video id.Custom fields form
The generated fields cover simple settings. For anything else — a picker of the app's own, values from the app's own data or context, a script — a plugin gives its own
form: any Svelte component, shown in the block's fields bar below the fields (or alone, when the plugin has nofields).The form receives
PluginFormProps:propsprops = { ...props, image: id }): that is one edit of the block, with its own undo step.readonlyThe form is the app's code, so it takes its data wherever the app keeps it — its own modules, stores, or a Svelte context the app provides above the editor (plugin components are rendered beneath it). The editor knows nothing about it. A
photoblock, for example, stores the id of an image of the app's library and offers the images of the album the app names in a context of its own:// images.ts — the app's own data and context import { getContext, setContext } from 'svelte'; export const IMAGES = [ { id: 'ocean', album: 'cool', url: '/img/ocean.jpg' }, { id: 'sunrise', album: 'warm', url: '/img/sunrise.jpg' } ]; export const findImage = (id: unknown) => IMAGES.find((i) => i.id === id); export const provideAlbum = (get: () => string) => setContext('app:album', get); export const useAlbum = (): (() => string) => getContext<() => string>('app:album') ?? (() => 'cool');<!-- PhotoForm.svelte --> <script lang="ts"> import type { PluginFormProps } from '@atom-forge/brickee'; import { IMAGES, useAlbum } from './images'; import type { PhotoProps } from './PhotoView.svelte'; let { props = $bindable() }: PluginFormProps<PhotoProps> = $props(); const album = useAlbum(); </script> {#each IMAGES.filter((m) => m.album === album()) as m (m.id)} <button type="button" onclick={() => (props = { ...props, image: m.id })}> <img src={m.url} alt={m.id} width="64" /> </button> {/each}// photo.ts export const photo: BlockPlugin<PhotoProps> = { type: 'photo', // … props: () => ({ image: '', alt: '' }), fields: [{ key: 'alt', label: 'Alt text', kind: 'text', placeholder: 'What the image shows' }], form: PhotoForm, view: PhotoView, // shows findImage(props.image) preview: PhotoPreview, // the same, for the site markdown: (p) => { const url = findImage(p.image)?.url; return url ? `` : ''; } };The host sets the album around the editor with
provideAlbum(() => album).markdownruns outside components (copying blocks,toMarkdown), so it can use module data only, not a context. The stored id is a prop like any other, so it is untrusted: the view and the preview resolve it with the app's own lookup and render nothing for an unknown one.The view
The view receives
PluginViewProps:propsblocks[]for a plugin without content.readonlypalette,pluginsaccepts) and plugins, for a nested editor.Declare
propsandblockswith$bindable()even when the view does not use them. The fields are drawn above the view automatically; a view only has to show the block.Empty(propsiconandtext) is the dashed placeholder the bundled plugins show until their props are set; its text is translated.The preview
The preview receives
PluginPreviewProps:props,blocksandplugins. It is a plain Svelte component that renders the block for the site. UI text is available throughuseText(see Host contexts); anything else the app knows reaches it through the app's own modules and contexts.Containers
A plugin with
content: 'blocks'holds a nested document inblocks. Its view usesFrame, a thin box that draws the block's fields on its top and a nested editor below; its preview renders the inner blocks with a nestedPreview.<!-- NoteView.svelte --> <script lang="ts" module> export interface NoteProps extends Record<string, unknown> { title: string; } </script> <script lang="ts"> import { Frame, useText, type PluginViewProps } from '@atom-forge/brickee'; let { props = $bindable(), blocks = $bindable(), readonly, palette, plugins }: PluginViewProps<NoteProps> = $props(); const tr = useText(); </script> <Frame bind:blocks {readonly} {palette} {plugins} heading={props.title} empty={tr('Note')} placeholder={tr('Write the note…')} /><!-- NotePreview.svelte --> <script lang="ts"> import { Preview, type PluginPreviewProps } from '@atom-forge/brickee'; import type { NoteProps } from './NoteView.svelte'; let { props, blocks, plugins }: PluginPreviewProps<NoteProps> = $props(); </script> <aside class="note"> {#if props.title}<p class="note-title">{props.title}</p>{/if} <Preview {blocks} {plugins} nested /> </aside>// note.ts import { StickyNote } from '@lucide/svelte'; import { mdJoin, mdQuote, mdText, type BlockPlugin } from '@atom-forge/brickee'; import NoteView, { type NoteProps } from './NoteView.svelte'; import NotePreview from './NotePreview.svelte'; export const note: BlockPlugin<NoteProps> = { type: 'note', label: 'Note', hint: 'Boxed text with a title', keys: 'note aside box', icon: StickyNote, props: () => ({ title: '' }), fields: [{ key: 'title', label: 'Title', kind: 'text' }], tag: () => 'note', content: 'blocks', accepts: ['md:p', 'md:ul', 'md:ol', 'youtube'], markdown: (p, { inner }) => mdQuote(mdJoin(p.title && `**${mdText(p.title)}**`, inner)), view: NoteView, preview: NotePreview };Frameprops:blocks(bindable),readonly,palette,plugins, and optionallyplaceholderfor the nested editor.heading,emptyandimage(a URL) make a heading line, which is shown only when the fields are not (read-only mode or no fields).How nesting works:
acceptsnarrows what the nested editor offers to the listed palette ids, in the host's order.'md:*'stands for every built-in block, so['md:*', 'youtube']is "text and videos". Withoutaccepts, the nested editor offers everything the host does (minus containers and unique blocks).palettestill applies:acceptscan only narrow it, never add to it.blocksSchemaFor(plugins)checksacceptson the server (see On the server).Unique blocks
unique: true— at most one per document, at the top level (a table of contents, for example). Once the document has one, the plugin leaves the slash and Turn-into menus, a second one pasted in falls back to its markdown form, and nested editors never offer it. The schema does not enforce it.Markdown form
markdown(props, { inner })returns the block as markdown, used when blocks are copied in the editor and bytoMarkdown.inneris the nested blocks already as markdown (''without any).Return
''to leave the block out. Plugins whose output has no meaning as text (an ad slot, the bundledgap) simply have no markdown form. Three helpers keep the output well-formed:mdText(value)#, joins lines.mdJoin(...parts)mdQuote(md)>, for a box rendered as a blockquote.Taking pasted tables
When markdown with a GFM table is pasted into the editor, or imported with
fromMarkdown(text, { plugins }), the table goes to the first plugin that hasfromTable. It gets the table and returns the new block's props:interface MarkdownTable { rows: string[][]; // the cells as inline markdown, row by row; the first row is the header align: ('left' | 'center' | 'right')[]; // per column, from the delimiter row (:--, :-:, --:) } fromTable?(table: MarkdownTable): P;The bundled
tablehas it (fromTable: ({ rows, align }) => ({ rows, heads: ['top'], align })), so a table pasted into an editor that offers it becomes a table block. Without such a plugin the table stays text.Inline plugins
An inline plugin is an element inside a block's text — a formula, a mention, a variable — that moves and deletes as one, while the stored text stays inline markdown. Give the same list to the editor and the preview (
inlinePlugins); nested editors and plugin views (a table's cells) get it through a context (useInlinePlugins()).interface InlinePlugin<D extends Record<string, string>> { type: string; label: string; icon: Icon; pattern: RegExp; // its markdown form in the text (global, bounded) parse(match: string[]): D; // a match → the data markdown(data: D): string; // the data → its markdown form (parse of it gives the same data) render(data: D): string; // the data → safe HTML (escape what comes from the data) fields: PropField[]; // edited in a popup when the element is clicked create(text: string): D; // a new one from the selected or typed text typing?: { open: string; close: string }; // typing open…close and a space makes one }How it works:
inline()looks for the patterns outside code spans and escaped characters, and putsrender's HTML in a span that carries the markdown form (data-md); the editor's span is not editable text. Converting back to markdown takes thedata-md, so a document saves the same even where the plugin is missing (its markdown form then shows as text). The toolbar gets a button per inline plugin, a click on an element opens its fields, andtypingworks like**bold**.inlineMathin@atom-forge/brickee/mathis the bundled example.Taking files
When files are pasted into the editor (a copied image, a screenshot) or dropped on it from outside the page, the first plugin the editor offers that has
fromFilesand returns props gets one block of its own:fromFiles?(files: File[]): P | null | Promise<P | null>;Return
nullto leave the files to the next plugin. Uploading and storing them is the plugin's business, so it may return a promise — upload, then return the props with the stored URL or id. A pasted file goes after the block with the caret (or in place of an empty one); a dropped one where the drop line shows.fromFiles: async (files) => { const file = files.find((f) => f.type.startsWith('image/')); if (!file) return null; const url = await uploadToMyStorage(file); // your app's upload return { url, alt: file.name }; },The kit
FrameEmptysafeColor(value, fallback)#hexcolour (3–8 digits), or the fallback.lines(text)parsefor "one per line" lists.mdText,mdJoin,mdQuoteuseTextPreviewnested).