Migrate from ProseMirror, Slate or Lexical
Convert stored ProseMirror/Tiptap, Slate and Lexical JSON into GoTipe documents that fit the GoTipe schema, keeping unsupported content visible instead of dropping it.
@gotipe/migration converts the JSON that ProseMirror (and Tiptap), Slate and Lexical store into GoTipe documents. It does not load those editors. It converts data only: plugins, history, selection, collaboration state and user interface are not migrated.
The document uses only the block types, attributes and nesting that GoTipe's own extensions declare, so it passes editor.validate() with the stock presets. Nothing is dropped silently: source fields GoTipe has no attribute for are listed in the result, and content the converter cannot represent is kept as a raw block with its original JSON and a warning.
Install
npm install @gotipe/migration @gotipe/core @gotipe/markdownpnpm add @gotipe/migration @gotipe/core @gotipe/markdownyarn add @gotipe/migration @gotipe/core @gotipe/markdownbun add @gotipe/migration @gotipe/core @gotipe/markdown@gotipe/markdown provides the node spec of the raw block that holds preserved content.
Convert a document
import { createEditor, defineExtension } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
import { markdownRawNodeSpec } from "@gotipe/markdown";
import { convertProseMirrorToGoTipe } from "@gotipe/migration";
// Preserved source content arrives in `markdownRaw` blocks.
const MarkdownRaw = defineExtension({ name: "markdownRaw", nodes: [markdownRawNodeSpec] });
const editor = await createEditor({ extensions: [...DefaultPreset, MarkdownRaw] });
const result = convertProseMirrorToGoTipe({
type: "doc",
content: [
{ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Notes" }] },
{
type: "paragraph",
content: [{ type: "text", text: "Привет 😀", marks: [{ type: "bold" }] }],
},
],
});
console.log(result.warnings); // []
console.log(result.preserved, result.unmapped); // [] []
if (!editor.validate(result.document)) throw new Error("Migrated document does not fit the schema");
editor.setContent(result.document);Keep the source data until you have checked the result on your own documents.
| Source | Function | Input |
|---|---|---|
| ProseMirror, Tiptap | convert |
{ type: "doc", content: [ |
| Slate | convert |
An array of elements |
| Lexical | convert |
Serialized state { root: { type: "root", children: [ |
Options
| Option | Type | Default | Description |
|---|---|---|---|
strict |
boolean |
false |
Throw Unsupported on the first node or mark that cannot be converted, instead of preserving it. |
onWarning |
( |
— | Called with each warning of the result when the conversion has finished. |
blockTypeMap |
Record< |
— | Maps more source node names to block types, for example { callout: "callout" }. |
markTypeMap |
Record< |
— | Maps more source mark names to mark types. |
createId |
() => string |
createId() of @gotipe/core |
Makes IDs for blocks without a usable source ID. Must return unique, non-empty strings. |
The maps rename types; they do not convert attributes or add behavior. A GoTipe type, such as callout, gets the attributes its schema declares and the rest goes to unmapped. A type of your own gets the source attributes as they are: its extension must declare them.
Result
| Field | Type | Description |
|---|---|---|
document |
Document |
The GoTipe document ({ version: 1, blocks }). |
warnings |
string[] |
Messages with source paths: preserved subtrees, replaced IDs, fields that do not fit. |
preserved |
Preserved |
One entry per preserved subtree: blockId of its raw block, source path, sourceType and reason. |
unmapped |
Unmapped |
Source fields that are not in the document: blockId of the block that holds the node (null for the root), path of the source object, sourceType and fields with the source values; a list or heading that became text of a table cell is a block field. In source order. |
preservedNodes |
number |
preserved.. |
skippedNodes |
number |
Always 0: the converters never drop content. |
What is converted
| Source | Blocks | Inline |
|---|---|---|
| ProseMirror, Tiptap | paragraph, heading, blockquote, code_block/codeBlock, bullet_list/bulletList, ordered_list/orderedList, list_item/listItem, taskList, taskItem, table, table_row/tableRow, table_cell/tableCell, table_header/tableHeader, image (also a paragraph that holds only an image), horizontal_rule/horizontalRule |
text, hard_break/hardBreak; marks bold/strong, italic/em, underline, strike/strikethrough, code, link, highlight, subscript, superscript, textColor, textStyle color and background color |
| Slate | paragraph (also elements without a type), heading with level, heading-one to heading-six, block-quote, code-block, bulleted-list, numbered-list, list-item, check-list, check-list-item, table, table-row, table-cell, table-header, image (url), horizontal-rule |
Text leaves with bold, italic, underline, strikethrough/strike, code, subscript, superscript, highlight, color; link elements with url or href |
| Lexical | paragraph, heading (h1–h6), quote, code, list (bullet, number, check), listitem, table, tablerow, tablecell (header state, spans, alignment), image (altText, also inside a paragraph), horizontalrule |
text with its format flags and color/background-color styles, link, autolink, linebreak, tab, code highlight tokens |
A source editor's plugins can add any node names; this table is what the converters know without maps.
What goes where
- Attributes. A block or mark gets the attributes the GoTipe schema declares, with a value of the declared type: heading
level, liststart, taskchecked, codelanguage(andmetafrom a prosemirror-markdown info string), cellcolspan,rowspanandalign, paragraph and headingalign, tablecolWidths, imagesrc,alt,widthandheight, linkhref,title,targetandrel, highlight and textcolor. Tiptap'stextAlign, Lexical'scolSpan,rowSpan,altText, theformatof a cell, paragraph or heading (left,center,right,justify) and a heading'stagare renamed to these; Slate'salignalready is one. - Everything else goes to
result.unmapped, tied to the block byblockId: Tiptap'scolwidthand imagetitle, text direction, the alignment of a paragraph that became a list item's or cell's text, Lexical'sindent,version, cellwidthand imagecaption, font family and size, other node fields. Anullvalue counts as unset and is left out. Each field that holds a value gets one warning per source type, such asLexical root.children[3]: paragraph field indent does not fit the GoTipe schema; kept in unmapped. Source defaults that change nothing a reader sees, such as Lexical'sversion,direction: "ltr",indent: 0or Tiptap'stextAlign: "left", are listed without a warning. - IDs. A source ID (a node's
id, orattrs.idin ProseMirror) becomes the block ID. A duplicate is replaced with a new ID and a warning. A replaced or unusable ID, and the ID of a paragraph that became its container's text, stay inunmappedas anidfield, so links to them can be remapped. New IDs are random, so converting twice gives different IDs unless you passcreateId. - Structure. The first paragraph of a list item, task, quote, callout or table cell becomes its own text. List items outside a list, such as Slate's top-level check-list items, get a list around them.
- Table cells. A cell holds text, not blocks, so its other paragraphs, headings and lists become lines of its text, with their marks. A list item starts with
•,1.(from the list's start),☐or☑, and a nested list is indented by two spaces per level. The table stays editable. Each list or heading is listed inunmappedas ablockfield, the GoTipe block it would have been, with a warning:ProseMirror/Tiptap content[0].content[1].content[0].content[1]: bulletList in tableCell became lines of its text; kept in unmapped. - Unsupported content. When a node holds something the converter cannot represent — an unknown node or mark, formatted text inside code, text mixed with child blocks, Lexical token text — the node becomes a
markdownRawblock withkind: "json"; its content is the source JSON, pretty-printed.result.preservedlists it. Where the schema allows no raw block, as in a table cell, a quote or a list, the nearest enclosing node that can be one is kept instead: a mention in a table cell keeps the whole table. The warning names both paths:ProseMirror/Tiptap content[3]: Inline node mention cannot be represented (at content[3].content[0].content[0].content[0]); source preserved as markdownRaw.
With strict: true, the first such case throws UnsupportedContent instead. Its path is the path in the source and its reason what could not be represented:
import { UnsupportedContent, convertLexicalToGoTipe } from "@gotipe/migration";
export function convertStrictly(state: unknown) {
try {
return convertLexicalToGoTipe(state, { strict: true });
} catch (error) {
if (error instanceof UnsupportedContent) console.error(error.path, error.reason);
throw error;
}
}Some input always throws a plain Error, in both modes: a wrong root, non-JSON values (functions, class instances, non-finite numbers), cycles, fields of the wrong type, and input beyond the limits below. The converters never load URLs or parse HTML.
| Limit | Value |
|---|---|
Nodes: objects with a type (nodes and marks) and Slate text leaves |
1,000,000 |
| Nodes inside nodes | 128 levels |
| Arrays and objects inside each other | 512 levels |
| JSON values of any kind | 16 Mi (16,777,216) |
| Text of all string values | 32 Mi UTF-16 code units |
The package's tests convert documents of 50,000 paragraphs in each format. The editor has its own limits: it rejects a document with more than 100,000 blocks or nested deeper than 64 levels, so check the result with editor.validate().
Check the result
The document validates with FullPreset, and with DefaultPreset unless it uses marks or blocks that preset lacks, such as subscript and superscript. Preserved content needs the markdownRaw node, registered from markdownRawNodeSpec as in the example above. A type you add through blockTypeMap needs your own extension. Call editor.validate(document) before setContent, which throws VALIDATION_ERROR for a document that does not fit.
unmapped is plain JSON. Store it next to the migrated document if you may need the source data later, or read the fields your application has its own attributes for by blockId.
Limitations
- The converters cover the common nodes of each editor; they are not a promise of compatibility with every third-party plugin.
- There are no converters for CKEditor, TinyMCE or Quill: export their content to HTML or Markdown and import that.
- Inline nodes such as mentions, hashtags, equations and inline images among text keep their whole paragraph as JSON.
- A code block, image, quote or table inside a table cell, also inside a list in the cell, keeps the whole table as JSON. A list or code block inside a quote keeps the whole quote.
- Lexical keeps a nested list in a list item of its own; it becomes an item without text that holds the list.
- Slate code blocks made of
code-lineelements are kept as JSON. - Saved as Markdown, a preserved block is written as its JSON text, like any
markdownRawblock. - Indentation of paragraphs and headings, text direction, column widths of Tiptap tables, image titles and captions, and font family and size have no GoTipe attribute. They are in
unmapped, not in the document. Alignment is kept (align), except on a paragraph that became a list item's or cell's text.