Plugins
What an Edytor plugin is, how to pass plugins to the editor, how plugin order decides conflicts, and which plugins ship with the package.
Everything the editor knows about content comes from plugins: block kinds, marks, inline atoms, key bindings, and hooks that can inspect or veto every edit. The core ships no block kinds of its own; <Edytor> adds the rich text and suggestions plugins by default, so <Edytor /> alone is a working rich text editor.
What a plugin is
A plugin is a function of the editor that returns definitions and hooks:
import type { Plugin } from 'edytor';
export const loggerPlugin: Plugin = (edytor) => ({
onBeforeOperation: ({ operation }) => {
console.log('about to run', operation);
},
onChange: (value) => {
console.log('document now has', value.children?.length, 'top-level blocks');
}
});
The function runs once, when the editor is created. It receives the Edytor instance, so it can keep state in its closure and call editor methods from its hooks. Everything it returns is optional:
| Field | What it contributes |
|---|---|
blocks |
Block kinds, see Blocks |
marks |
Text marks, see Marks |
inlineBlocks |
Inline atoms, see Inline blocks |
hotkeys |
Key bindings, see Hotkeys |
commands |
Named commands for menus such as the slash menu |
placeholder |
Text for empty blocks, see Placeholder |
onBeforeOperation and more |
Hooks into every edit, the DOM and the clipboard |
Writing plugins documents every field and hook.
Passing plugins to the editor
Pass an array to the plugins prop of <Edytor>:
<script lang="ts">
import {
Edytor,
createCodePlugin,
createSlashMenuPlugin,
createMarkdownShortcutsPlugin,
type SlashMenuController
} from 'edytor';
const plugins = [createCodePlugin(), createMarkdownShortcutsPlugin(), createSlashMenuPlugin({ menu })];
</script>
{#snippet menu(slash: SlashMenuController)}
<ul {@attach slash.popup}>
{#each slash.commands as command, index (command.id)}
<li {@attach slash.option(index)} onclick={() => void slash.run(command)}>{command.label}</li>
{/each}
</ul>
{/snippet}
<Edytor {plugins} />
A plugin with chrome (a menu, a toolbar, the block handles, a panel) ships its behavior and none of its markup: its factory takes the snippets that draw it, and without them it draws nothing (Menus and handles).
Plugins are read once, when the component mounts. Changing the array afterwards has no effect.
Default plugins
<Edytor> completes the list with the plugins every editor needs, after yours so your kinds, marks and keys take precedence, unless the list already has them:
| Plugin | Position | Replaced by |
|---|---|---|
createSuggestionsPlugin() (its keys, no bar) |
after yours | any createSuggestionsPlugin(...) in your list |
createRichTextPlugin() |
last | createRichTextPlugin() in your list |
The example above therefore runs your three plugins, then suggestions and rich text. A default you list yourself stays where you put it, so older code that passes plugins={[createRichTextPlugin()]} still works.
Some bundled plugins are not defaults: list createImagePlugin({ upload }), createArrowMovePlugin(), createColumnsPlugin(), createCodePlugin(), find, createMarqueePlugin(), comments, shared suggestions, the media plugins (embed, bookmark, file, video, audio), the page, table of contents, table and equation plugins, the block handles (drag and drop), the block menu, the slash menu, the toolbar and markdown shortcuts yourself when you want them. Nothing in the core adds any of them. So a bare <Edytor /> leaves Tab to the browser (the focus moves on; nesting is the allowNesting option, not a plugin), and ignores files dropped on it (dropping files needs a media plugin given an upload).
Pass defaultPlugins={false} to get exactly your list. The defaults are added by the <Edytor> component, per view; the editor instance underneath has none of its own.
Plugin order
The array order is the precedence order. Two rules follow from it:
- Definitions: first wins. When two plugins define the same block kind, mark or inline atom, the fields of the one listed first are used, and a field it leaves out is the later one’s: a plugin naming only a kind’s
snippet, listed first, restyles a bundled kind and keeps the rest of its definition (Restyling a kind). A command id is the first plugin’s whole. - Prevention: first wins. Hooks and key bindings run in list order. The first plugin that calls
prevent()stops the operation or claims the key, and the plugins after it are not asked.
Order therefore matters whenever two plugins touch the same thing: the same kind name, the same chord, or the same operation. A plugin that overrides or refuses something a bundled plugin does goes before it in the list. The two defaults are added after your plugins, so yours already come first; to let a default win over one of your plugins, list the default yourself before it.
One exception: two plugins that declare different defaultChild values for the same block kind are an error, whatever their order. The editor throws when it is created.
Why plugins are Svelte files
Block, mark and inline atom definitions render through Svelte snippets. A snippet can only be declared in a .svelte file, and a component’s <script module> block can reference the snippets declared in its markup. So a plugin that renders anything is usually a .svelte file that exports the plugin from <script module>:
<script module lang="ts">
import type { Snippet } from 'svelte';
import type { Plugin } from 'edytor';
export const highlightPlugin: Plugin = () => ({
marks: { marker: { snippet: marker } }
});
</script>
{#snippet marker({ content }: { content: Snippet })}
<mark class="marker">{@render content()}</mark>
{/snippet}
Import it like any other module: import { highlightPlugin } from './HighlightPlugin.svelte'. A plugin that only adds hooks or key bindings can be a plain .ts file.
Bundled plugins
| Plugin | Export | What it adds |
|---|---|---|
| Rich text | createRichTextPlugin() |
Paragraphs, headings, lists, to-dos, toggles, toggle headings, callouts, quotes, dividers, ten marks, and Notion’s shortcuts. On by default |
| Code | createCodePlugin() |
Code blocks with syntax highlighting and a Copy button |
| Image | createImagePlugin |
Notion’s image block: embed from a link or your upload, with an editable caption |
| Embed | createEmbedPlugin |
Notion’s embed block: a YouTube, Vimeo, Loom, Figma, CodePen or Spotify player in a sandboxed frame, from an allowlist you can extend. Opt-in |
| Bookmark | createBookmarkPlugin |
Notion’s web bookmark: a card with the page’s title, description and images from your unfurl. Opt-in |
| File | createFilePlugin |
Notion’s file block: an attachment uploaded or linked. Opt-in |
| Video and Audio | createVideoPlugin, createAudioPlugin |
Video and audio files in the browser’s players, linked or uploaded. Opt-in |
| Columns | createColumnsPlugin |
Notion’s multi-column layouts: drag a block beside another, “2 columns” to “5 columns”, resize by dragging the gap. Opt-in: list it in plugins |
| Table | createTablePlugin |
Notion’s simple table: cells of text in rows and columns, Tab between cells, rows and columns added, moved and deleted from the table’s edges and grips, header row and column. Opt-in |
| Block handles | createBlockHandlesPlugin |
A + and a drag grip (your handle) beside each block, drag and drop, keyboard moves. Opt-in |
| Block menu | createBlockMenuPlugin |
Notion’s block menu (your menu) on a grip click: search, Turn into, Color, Duplicate, Move, Delete |
| Slash menu | createSlashMenuPlugin |
A command menu (your menu) opened by typing / |
| Toolbar | createToolbarPlugin |
A floating toolbar (your toolbar) over text selections: Turn into, link, marks and colors |
| Markdown shortcuts | createMarkdownShortcutsPlugin() |
Block prefixes such as # or - , and inline **bold**, *italic*, `code`, ~strike~ |
| Arrow move | createArrowMovePlugin() |
Mod + Shift + ↑/↓ moves the caret’s block; Mod + ↑/↓ moves selected blocks |
| Find and replace | createFindPlugin |
Mod + F opens a find and replace bar: matches highlighted, closed toggles opened, Replace all in one undo step. Opt-in: list it in plugins |
| Marquee selection | createMarqueePlugin |
Notion’s rubber band: drag from the margins or below the last block to select blocks with a rectangle, live. Opt-in |
| Page | createPagePlugin |
Notion’s subpage block: a link to another document with its title, opened, named and created by your functions. Opt-in |
| Table of contents | createTocPlugin |
Notion’s table of contents: the document’s headings, live, each scrolling to its heading. Opt-in |
| Comments | createCommentsPlugin |
Notion’s comment threads on text: a sidebar beside it, replies, Resolve and Re-open, kept by the room. Opt-in |
| Mention | createMentionPlugin |
Notion’s @ mentions: a menu of your app’s people, picked into an inline mention. Opt-in |
| Page link | createPageLinkPlugin |
Notion’s [[ page links: a search of your app’s pages, picked into an inline link. Opt-in |
| Equation | createEquationPlugin |
Notion’s block and inline equations: TeX drawn by KaTeX, loaded from a CDN on demand, edited with a live preview. Opt-in |
| Shared suggestions | createSharedSuggestionsPlugin |
Google Docs’ suggesting mode: suggestions in the document, reviewed by every collaborator, accepted or rejected by a writer; AI answers streamed into the document live. Opt-in |
All exports come from the package root, edytor. The create… factories take options, including snippets that replace the menus’ and handles’ markup (see Menus and handles). For the matching document look, add the Notion theme.