Skip to content
Edit on GitHub

Extensions overview

The extensions that define GoTipe's blocks, marks and editing behaviours, the presets that bundle them and how they map to Markdown.

@gotipe/coreMIT

Every block type, mark and editing behaviour in GoTipe comes from an extension. An extension declares schema (nodes and marks), keyboard shortcuts, input rules, paste rules and "/" commands. The editor accepts only documents that its extensions describe, so the list you pass to createEditor is also the schema of your documents.

You can take a preset or pick extensions one by one:

editor.ts
import { createEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";

const editor = await createEditor({ extensions: [DefaultPreset] });
editor.mount(document.querySelector<HTMLElement>("#editor")!);

Extensions live in @gotipe/core/extensions, presets in @gotipe/core/presets. To write your own, see Extensions.

Presets

Preset Extensions
MinimalPreset Paragraph, Bold, Italic, History
DefaultPreset Paragraph, Heading (configured with levels 1–3), BulletList, OrderedList, ListItem, TodoList, CodeBlock, Image, Blockquote, Callout, Divider, Table, Toggle, Bold, Italic, Underline, Strikethrough, InlineCode, Link, Highlight, TextColor, History, Placeholder, DragAndDrop, SlashCommands
FullPreset Everything in DefaultPreset, plus Heading with levels 1–6, Columns, Embed, Math, File, Superscript, Subscript

A preset is a plain array of extensions, so you can extend or filter it:

editor.ts
import { createEditor } from "@gotipe/core";
import { Superscript, Subscript } from "@gotipe/core/extensions";
import { DefaultPreset } from "@gotipe/core/presets";

const editor = await createEditor({
  extensions: [
    DefaultPreset.filter((extension) => extension.name !== "toggle"),
    Superscript,
    Subscript,
  ],
});

PageEditor from @gotipe/block-editor uses its own set, pageExtensions(): the blocks and marks that GFM Markdown can hold (Paragraph, Heading 1–6, the three lists, CodeBlock, Image, File, Blockquote, Callout, Divider, Table, all ten marks, History) plus the read-only raw Markdown node and mark. See Page editor.

All extensions

The name in the second column is the extension's name and, unless noted, the name of the node or mark it adds.

Extension Name Presets Page
Paragraph paragraph Minimal, Default, Full Text blocks
Heading heading Default, Full Text blocks
Blockquote blockquote Default, Full Text blocks
Divider divider Default, Full Text blocks
Callout callout Default, Full Text blocks
Toggle toggle Default, Full Text blocks
Columns columns (nodes columns, column) Full Text blocks
BulletList bulletList Default, Full Lists
OrderedList orderedList Default, Full Lists
ListItem listItem Default, Full Lists
TodoList todoList (nodes todoList, todoItem) Default, Full Lists
CodeBlock codeBlock Default, Full Code block
Table table (nodes table, tableRow, tableCell, tableHeader) Default, Full Tables
Image image Default, Full Media
File file Full Media
Embed embed Full Media
Math math Full Math
Bold bold Minimal, Default, Full Marks
Italic italic Minimal, Default, Full Marks
Underline underline Default, Full Marks
Strikethrough strikethrough Default, Full Marks
InlineCode code Default, Full Marks
Link link Default, Full Marks
Highlight highlight Default, Full Marks
TextColor textColor Default, Full Marks
Superscript superscript Full Marks
Subscript subscript Full Marks
History history Minimal, Default, Full Behaviours
Placeholder placeholder Default, Full Behaviours
SlashCommands slashCommands Default, Full Behaviours
DragAndDrop dragAndDrop Default, Full Behaviours
FindReplace findReplace — Find and replace
CharacterCount characterCount — Character count
Typography typography — Typography
Autolink autolink — Links and paste
LinkOnPaste linkOnPaste — Links and paste
MarkdownPaste markdownPaste — Links and paste
TextAlign textAlign (attribute align of paragraph and heading) — Text alignment
TrailingNode trailingNode — Editing aids
InvisibleCharacters invisibleCharacters — Editing aids
Focus focus — Editing aids

The extensions without a preset add no nodes or marks. Add them after a preset.

Configure an extension

configure(options) returns a copy of the extension with the options merged in. The original stays unchanged.

editor.ts
import { createEditor } from "@gotipe/core";
import { Image, Placeholder } from "@gotipe/core/extensions";
import { DefaultPreset } from "@gotipe/core/presets";

const editor = await createEditor({
  extensions: [
    DefaultPreset,
    Image.configure({ maxSize: 5 * 1024 * 1024 }),
    Placeholder.configure({ text: "Write something" }),
  ],
});

The editor flattens nested arrays and keeps one extension per name. When a name repeats, the last configuration wins and the extension keeps the position of its first occurrence. That is how [DefaultPreset, Heading.configure({ levels: [1, 2] })] replaces the preset's Heading. Shortcuts and input rules are tried in that order, and the first match handles the key or the text.

Extension Options Page
Image maxSize, allowedTypes, upload Media
Placeholder text Behaviours
Heading levels Text blocks
CodeBlock languages, defaultLanguage, syntaxHighlight Code block

The other built-in extensions have no options.

Note:

In this release the CodeBlock options are accepted but not read by the editor or its UI; its page says what that means in practice.

Attributes every node accepts

Besides its own attributes, every node accepts five optional attributes: marker, delimiter, spread and breaks, which the Markdown codec uses to keep list markers, numbering delimiters, loose lists and hard line breaks, and a string style, which the shipped renderers do not apply. Any other attribute must be declared by an extension: a document with an undeclared attribute is rejected, not cleaned up.

Markdown at a glance

Node or mark Markdown
paragraph A paragraph; a line break in the text is a line break
heading # to ######; setext headings are read as well
bulletList, listItem -, * or + items; the marker is kept
orderedList 1. or 1) items; the start number and delimiter are kept
todoList, todoItem - [ ] and - [x] items
blockquote > with one paragraph
callout GFM alert: > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]
codeBlock Fenced code with its language and meta
divider ---
table GFM table with column alignment
image A paragraph holding only ![alt](src "caption")
file A paragraph holding only [name](path), where the text is the file name
bold, italic, strikethrough, code **text**, *text*, ~~text~~, `text`
link [text](href "title") or an autolink
underline, superscript, subscript <u>, <sup>, <sub>
highlight, textColor <mark> or <mark style="background:…">, <span style="color:…">

Markdown that the editor cannot edit (HTML blocks, footnotes, link definitions and a few list and quote shapes) is kept byte for byte as a read-only markdownRaw block or mdRaw text. The Markdown page has the full mapping.

Note:

toggle, columns, embed and math have no Markdown form. When written to Markdown, a toggle and columns become their content, a math block becomes its TeX source as plain text, and an embed is left out.

  • Extensions: define your own nodes, marks and commands.
  • Commands: the command chain used on these pages.
  • Document model: blocks, content and attributes.
  • Markdown: the codec behind getMarkdown() and PageEditor.