Extensions overview
The extensions that define GoTipe's blocks, marks and editing behaviours, the presets that bundle them and how they map to Markdown.
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:
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:
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 |
Invisible |
invisible |
— | 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.
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.
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 , where the text is the file name |
bold, italic, strikethrough, code |
**text**, *text*, ~~text~~, `text` |
link |
[ or an autolink |
underline, superscript, subscript |
<u>, <sup>, <sub> |
highlight, textColor |
<mark> or <, < |
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.
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.
Related
- 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()andPageEditor.