Writing extensions
Define block and mark types, keyboard shortcuts, input and paste rules, slash commands and plugins with defineExtension.
An extension adds to the editor's schema and behaviour: node types for blocks, mark types for text, keyboard shortcuts, typing and paste rules, slash commands and a plugin with state and decorations. Every built-in feature is an extension, and the presets are arrays of them. Write one when you need a block type or a behaviour that GoTipe doesn't have.
Define an extension
import { defineExtension } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
const Shortcuts = defineExtension({
name: "shortcuts",
keybindings: [{ key: "Mod-Shift-l", command: (editor) => editor.chain().toggleBulletList().run() }],
});
const extensions = [DefaultPreset, Shortcuts];defineExtension<Options>(config) returns an extension with configure(options), which returns a new extension whose options are shallowly merged over the defaults. The original is unchanged.
| Field | Type | Description |
|---|---|---|
name |
string |
Unique name. A later extension with the same name replaces the earlier one. |
dependencies |
string[] |
Names of extensions this one needs; they are set up first. A name that isn't in the list rejects createEditor. |
nodes |
NodeSpec[] |
Block types. |
marks |
MarkSpec[] |
Mark types. |
keybindings |
Keybinding[] |
Keyboard shortcuts. |
inputRules |
InputRule[] |
Rules that run after typing. |
pasteRules |
PasteRule[] |
Rules that handle pasted text or files. |
transform |
( |
Changes plain pasted text before it is inserted. |
parsePastedText |
( |
Turns plain pasted text into blocks. |
atomSupport |
Inline |
Collaboration repair and HTML read-back of atomic marks. The built-in atom extensions carry it; reuse theirs for your own (atom). |
slashCommands |
Slash |
Entries for the slash menu. |
plugin |
( |
State, transaction hooks and decorations. |
options |
Options |
Default options. |
onCreate, onUpdate, onDestroy |
( |
Lifecycle hooks. |
To change an extension that a preset already contains, add the configured version after the preset: [DefaultPreset, Image.configure({ maxSize: 2 * 1024 * 1024 })], with Image from @gotipe/core/extensions.
Node types
import type { NodeSpec } from "@gotipe/core";
const nodes: NodeSpec[] = [
{
name: "note",
group: ["block"],
content: "richText",
attrs: { tone: { type: "enum", values: ["info", "warning"], default: "info" } },
topLevel: true,
marksAllowed: "all",
leaf: false,
allowsChildren: false,
},
];| Field | Type | Description |
|---|---|---|
name |
string |
The value of Block.type. |
group |
string[] |
Group names, such as [. Stored in the schema; nesting is checked with childTypes. |
content |
"rich |
What Block.content holds: spans, a string or null. Commands and both engines convert content by it, as for the built-in types; Enter in a rawText block is a line break. |
attrs |
Record< |
Declared attributes. |
topLevel |
boolean |
Whether the block may appear at the top level of the document. |
marksAllowed |
"all" | "none" | string[] |
Marks allowed in the block's text. |
leaf |
boolean |
A leaf never has children. |
allowsChildren |
boolean |
Whether the block may have child blocks. |
childTypes |
string[] |
Allowed child types. Omit to allow any type. |
Inside defineExtension the fields are typed for you. Declared on their own, annotate them with NodeSpec, MarkSpec, Keybinding or InputRule from @gotipe/core, as the snippets on this page do.
Attributes
| Field | Type | Description |
|---|---|---|
type |
"string" | "number" | "bool" | "enum" | "array" | "object" |
Value type. Numbers must be finite. |
values |
string[] or number[] |
Allowed values of an enum. For another type, the values commands create, such as Heading levels; documents may hold others. |
required |
boolean |
The attribute must be present and not null. Default false. |
default |
unknown |
Written by commands into a new block or mark that leaves the attribute out. Steps you dispatch are applied as written. |
Mark types
import type { MarkSpec } from "@gotipe/core";
const marks: MarkSpec[] = [
{ name: "keyword", attrs: { term: { type: "string", required: true } }, rank: 20 },
];| Field | Type | Description |
|---|---|---|
name |
string |
The value of Mark.type. |
attrs |
Record< |
Mark attributes. |
rank |
number |
Stored in the schema. |
exclusiveGroup |
string |
Marks of one group exclude each other: adding one removes the others from that text. |
Adjacent spans merge only when their marks are equal, so give a mark only the attributes that matter. The renderers draw built-in marks; for your own marks, see limitations.
Keyboard shortcuts
import type { Keybinding } from "@gotipe/core";
const keybindings: Keybinding[] = [
{
key: "Mod-Alt-n",
command: (editor) => editor.chain().setBlockType("note", { tone: "info" }).run(),
},
// The Table extension's binding. At the table's last cell run() returns false,
// so Tab falls through to the browser instead of entering the next table.
{ key: "Tab", when: "inTable", command: (editor) => editor.chain().goToNextCell().run() },
];keyis a list of parts joined by-, case-insensitive. Modifiers areMod(Cmd on macOS, Ctrl elsewhere),ShiftandAlt; the last part is the key:b,Enter,Tab,ArrowUp,.. Modifiers match exactly:Mod-bdoesn't fire with Shift held.- Letters and digits also match by physical key, so shortcuts work on non-Latin layouts.
whenlimits a binding to the caret's surroundings:inTable,inCodeBlock,inListorinBlockquote. Any other value always matches.- Bindings are tried in extension order while the editor is editable. The first command that doesn't return
falsehandles the key, and its default action is prevented.
Input rules
import type { InputRule } from "@gotipe/core";
// "->" typed at the end of a block becomes an arrow.
const arrow: InputRule = {
pattern: /->$/,
handler: (editor) => {
const { anchor, head } = editor.getViewState().selection;
if (anchor.blockId !== head.blockId || anchor.offset !== head.offset || anchor.offset < 2) return;
const at = anchor.offset - 2;
editor.dispatch({
steps: [
{ type: "deleteText", blockId: anchor.blockId, from: at, to: anchor.offset },
{ type: "insertText", blockId: anchor.blockId, offset: at, text: "→", marks: [] },
],
selection: { type: "cursor", blockId: anchor.blockId, offset: at + 1 },
});
},
};After each typed input in a rich-text block, the editor tests every rule, in extension order, against the whole text of the block, not only the text before the caret. The first match calls handler(editor, match) and stops, unless the handler returns false: then the next rule is tried. Anchor patterns with ^ and $; here $ is the end of the block, so typing -> in the middle of a line does nothing. To act at the caret anywhere in a line, match loosely and let the handler check the text before the caret and return false when it doesn't fit, as the built-in **bold** rules do.
The typed text is already in the document when the handler runs, so the handler's changes are a separate undo step. Rules don't run in raw-text blocks or for text committed by an IME.
Paste rules
import { defineExtension } from "@gotipe/core";
export const PasteLinks = defineExtension({
name: "pasteLinks",
pasteRules: [
{
match: /^https?:\/\/\S+$/,
handler: (editor, data) => {
if (typeof data !== "string") return;
const { anchor, head } = editor.getViewState().selection;
if (anchor.blockId !== head.blockId) {
editor.chain().insertText(data).run();
return;
}
const from = Math.min(anchor.offset, head.offset);
editor.chain().insertText(data).addMark("link", from, from + data.length, { href: data }).run();
},
},
],
});matchis tested against the clipboard's plain text, or the MIME type of each pasted or dropped file. Content copied from a GoTipe editor keeps its structure and skips text rules. The built-inImageextension has a rule forimage/*.- The first matching rule handles the entry.
handler(editor, data, options)gets a draft editor with the same schema and host (JS engine, without plugins or hooks), the text orFile, and the extension's options. It may be async. - When the handlers finish, the draft's changes are committed as one undoable transaction. If the document or selection changed in the meantime, the result is discarded with a
CLIPBOARD_FAILEDerror. If a handler throws, nothing is inserted and the error is reported; the paste doesn't fall back to plain insertion.
Pasted text
Two hooks act on plain clipboard text, after the paste rules and only when the clipboard holds neither content copied from a GoTipe editor nor HTML:
import { createId, defineExtension } from "@gotipe/core";
export const PasteHooks = defineExtension({
name: "pasteHooks",
// Runs first, in extension order. Returning "" pastes nothing.
transformPastedText: (text) => text.replace(/\u00a0/g, " "),
// The first extension that returns blocks decides; null leaves the text to the next one.
parsePastedText: (text, { nodes }) =>
"heading" in nodes && /^TITLE: /.test(text)
? [
{
id: createId(),
type: "heading",
attrs: { level: 1 },
content: [{ text: text.slice(7), marks: [] }],
children: [],
},
]
: null,
});context is { editor, nodes, marks, options, safeHref, safeImageSrc }: the live editor, the node and mark specs of its schema by name, this extension's options, and the editor's own address checks for links and images (they return the address, or null when it is unsafe).
- Without a parser, or when all return
null, the text becomes one paragraph per line, as without the hooks. - Parsers are not asked when the caret is in a raw-text block such as code: the text is inserted as it is.
- The blocks get new IDs and are inserted as one undoable transaction. If they cannot go where the caret is (block structure inside a table cell) or the result does not match the schema, the text is pasted as plain paragraphs instead.
- CharacterCount uses the first hook, MarkdownPaste the second.
Slash commands
| Field | Type | Description |
|---|---|---|
name |
string |
Menu label. |
aliases |
string[] |
Extra search terms. |
description |
string |
Optional second line. |
icon |
string |
Icon name. The ready UI shows the first letter of name for names it doesn't know. |
group |
"ai" | "style" | "insert" | "upload" | string |
Menu section. |
execute |
( |
Runs the command. |
shouldShow |
( |
Optional; hide the command when it returns false. |
editor.getSlashCommands() returns the commands of all extensions in order. The slash menu of BlockEditor lists them and removes the typed /query before calling execute; see menus.
Plugins and decorations
plugin(options) is called once per editor with the configured options and returns optional hooks:
| Hook | When |
|---|---|
init(state) |
Once, after the document and the initial selection exist. |
apply( |
After each committed local transaction. Not for Undo, setContent or remote updates. |
decorations( |
After every update and selectionChange. The result replaces the layer extension:. |
destroy() |
When the editor is destroyed or its creation fails. |
state is { doc, selection } with detached copies. Decorations add presentation without changing the document: inline wraps text [from, to) with a class or attributes, widget shows non-editable text at an offset, node adds a class or attributes to a block, and blocks shows read-only blocks before or after a block. Outside plugins, set a layer with editor.setDecorations(layer, decorations).
EditorContent of @gotipe/react and of @gotipe/vue draw every layer. Besides the four generic kinds they draw the decorations of the built-in features with fixed classes:
| Decoration | Drawn as |
|---|---|
placeholder |
data-placeholder on the empty block, while editable |
comment-highlight |
<, plus resolved |
suggestion-insert, suggestion-delete |
< or -delete, with data-suggestion-id |
remote-selection |
< tinted with the person's color |
remote-cursor |
A widget < with gotipe-remote-cursor-caret and gotipe-remote-cursor-label |
ghost-text |
A widget < |
A range is wrapped in <span data-gotipe-decoration>; a widget is contenteditable="false" with data-gotipe-widget and never counts in offsets. Colors of people pass toSafeColor. When only decorations change, both renderers keep the native caret where it was.
While the browser composes text with an IME (editor.isComposing), the composing block belongs to the browser: setDecorations waits until the composition ends, both renderers keep the block's decorations as they were drawn and leave the native selection alone, and the new decorations are drawn when the composition ends.
A placeholder decoration with an empty text asks for the renderer's own words: React shows its placeholder for that block in the interface language, Vue asks the placeholder function you pass to EditorContent.
To draw a layer yourself, pass its name in hostLayers (EditorContent of both adapters, and Editor of @gotipe/react): the renderer leaves that layer out and still draws the rest. BlockEditor does this for collaboration and draws those people with its overlay.
Lifecycle
- The editor flattens the extension list, keeps the last extension of each name and orders dependencies first. A dependency cycle rejects
createEditorwithEXTENSION_DEPENDENCY_CYCLE; a dependency that isn't in the list, withEXTENSION_ERRORwhosedetailsname theextensionand the missingdependency. - It builds the schema from all node and mark types and validates the document.
- For each extension in order:
plugin(options),plugin.init(state), thenonCreate(editor). An exception here rejectscreateEditor; what was created is cleaned up. - While the editor runs,
onUpdate(editor)follows everyupdateevent. destroy()runsplugin.destroy()andonDestroy(editor)in reverse order and clears each extension's decorations.
Errors in apply, decorations, onUpdate and destroy are reported as EXTENSION_ERROR through the error event; the editor keeps running.
editor.hasExtension(name) tells whether the editor was created with an extension of that name, passed alone or in a preset. The set is fixed at creation and is the same on both engines. A UI asks it before offering what only an extension answers: BlockEditor shows its AI controls only for defineAi and its companions (AI UI).
Only plugin and paste-rule handlers receive the options as an argument. Lifecycle hooks written as methods can read them as this.options. Shortcuts, input rules and slash commands don't see options; build the extension in a function if they need them.
Complete example
A note block with a tone, a shortcut, an input rule, a slash command and a plugin that highlights a configurable keyword.
import { type Block, type Decoration, defineExtension } from "@gotipe/core";
export interface NoteOptions {
/** Text highlighted inside notes. */
keyword: string;
}
function findKeyword(blocks: Block[], keyword: string, found: Decoration[] = []): Decoration[] {
for (const block of blocks) {
if (block.type === "note" && Array.isArray(block.content) && keyword) {
const text = block.content.map((span) => span.text).join("");
for (let from = text.indexOf(keyword); from !== -1; from = text.indexOf(keyword, from + 1)) {
found.push({
type: "inline",
key: `keyword-${from}`,
blockId: block.id,
from,
to: from + keyword.length,
className: "note-keyword",
});
}
}
findKeyword(block.children, keyword, found);
}
return found;
}
export const Note = defineExtension<NoteOptions>({
name: "note",
options: { keyword: "TODO" },
nodes: [
{
name: "note",
group: ["block"],
content: "richText",
attrs: { tone: { type: "enum", values: ["info", "warning"], default: "info" } },
topLevel: true,
marksAllowed: "all",
leaf: false,
allowsChildren: false,
},
],
keybindings: [
{
key: "Mod-Alt-n",
command: (editor) => editor.chain().setBlockType("note", { tone: "info" }).run(),
},
],
inputRules: [
{
// "!! " typed into an empty paragraph turns it into a note.
pattern: /^!!\s$/,
handler: (editor, match) => {
const block = editor.getCurrentBlock();
if (block?.type !== "paragraph") return;
editor.dispatch({
steps: [
{ type: "deleteText", blockId: block.id, from: 0, to: match[0].length },
{ type: "setBlockType", blockId: block.id, newType: "note", attrs: { tone: "info" } },
],
});
},
},
],
slashCommands: [
{
name: "Note",
aliases: ["callout", "warning"],
description: "Highlighted note",
icon: "alert-circle",
group: "style",
execute: (editor) => {
editor.chain().setBlockType("note", { tone: "info" }).run();
},
},
],
plugin: (options) => {
const { keyword } = options as NoteOptions;
return { decorations: (state) => findKeyword(state.doc.blocks, keyword) };
},
});The renderer needs a view for the new type. With @gotipe/react, pass it in blockViews; spread rootProps on the root element so the editor can find the block:
import type { BlockViewProps } from "@gotipe/react";
import type { HTMLAttributes } from "react";
export function NoteView({ block, rootProps, content }: BlockViewProps) {
const tone = block.attrs.tone === "warning" ? "warning" : "info";
return (
<aside
{...(rootProps as HTMLAttributes<HTMLElement>)}
data-block-type="note"
data-tone={tone}
className={["note", rootProps.className].filter(Boolean).join(" ")}
>
{content}
</aside>
);
}import { DefaultPreset } from "@gotipe/core/presets";
import { EditorContent, useEditor } from "@gotipe/react";
import { Note } from "./note";
import { NoteView } from "./NoteView";
import "./note.css";
export function Editor() {
const editor = useEditor({
extensions: [DefaultPreset, Note.configure({ keyword: "FIXME" })],
engine: "js",
});
return <EditorContent editor={editor} blockViews={{ note: NoteView }} />;
}.note { margin: 8px 0; padding: 12px 16px; border-left: 4px solid #2c62d4; background: #e6ecfa; }
.note[data-tone="warning"] { border-left-color: #9a6500; background: #fbf0ce; }
.note-keyword { font-weight: 600; text-decoration: underline; }BlockEditor takes the same blockViews prop and also lists the slash command.
Limitations
rankis stored in the schema but not used yet.- The React and Vue renderers draw only the built-in marks; text with your own mark renders unformatted. Use an
inlinedecoration to show it. - HTML and Markdown output write an unknown block as a paragraph with its text, without its type and attributes. Server rendering can take your own HTML for it; see content formats.
accessibilityandstorageKeyexist on the extension type but the core doesn't read them.