Skip to content
Edit on GitHub

Quick start

Put a working GoTipe editor on the page with React, Markdown, a headless setup or Vue.

@gotipe/block-editor@gotipe/core@gotipe/react@gotipe/vue

Four ways to get an editor running. The first two use the ready UI from @gotipe/block-editor (commercial); the last two use only MIT packages and your own controls. All four run on the JS engine, so they need no WebAssembly setup. If your bundler reports that it can't resolve @gotipe/wasm, add the alias from installation.

Live editorType / for blocks
Loading the editor…

Install

For BlockEditor or PageEditor:

npm install @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-dom

For a headless React editor:

npm install @gotipe/core @gotipe/react react react-dom

For Vue:

npm install @gotipe/core @gotipe/vue vue

Create an editor

Editor.tsx
import { BlockEditor } from "@gotipe/block-editor";
import { FullPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import "@gotipe/theme/base.css";
import "@gotipe/theme/theme.css";

const INITIAL = {
  version: 1,
  blocks: [
    {
      id: "title",
      type: "heading",
      attrs: { level: 1 },
      content: [{ text: "Welcome", marks: [] }],
      children: [],
    },
    {
      id: "intro",
      type: "paragraph",
      attrs: {},
      content: [
        { text: "Type ", marks: [] },
        { text: "/", marks: [{ type: "code", attrs: {} }] },
        { text: " to insert a block.", marks: [] },
      ],
      children: [],
    },
  ],
};

export function Editor() {
  const editor = useEditor({
    extensions: [FullPreset],
    content: INITIAL,
    engine: "js",
    onUpdate: ({ editor }) => localStorage.setItem("doc", JSON.stringify(editor.getJSON())),
  });
  return <BlockEditor editor={editor} showAiCommandBar={false} />;
}

What happens here:

  • useEditor creates the editor once, when the component mounts, and destroys it on unmount. It returns null (React) or a ref holding null (Vue) until the editor is ready. Options are read once; later changes to them are ignored.
  • BlockEditor shows a loading skeleton while editor is null. showAiCommandBar is turned off here; without the AI extensions the editor shows no AI controls anyway.
  • PageEditor creates its own editor. After edits it calls onChange with the whole Markdown text, at most once per animation frame; debounce saving in your code. Blocks you did not touch keep their original bytes.
  • EditorContent mounts the editor on its element and renders the blocks. Toolbar buttons call commands; focus() returns the caret to the document before the command runs.
  • EditorContent shows images and files read-only. To upload, resize, crop or caption them, wrap it in <MediaBlocksContext.Provider value={mediaBlocks}> with mediaBlocks from @gotipe/react/media (see React); BlockEditor and PageEditor already include it.

Editor options

useEditor takes the options of createEditor from @gotipe/core:

Option Type Default Description
extensions (Extension | Extension[])[] required Block types, marks and behaviour. Presets are arrays and mix with single extensions.
content object | string one empty paragraph Document JSON, or an HTML string (browser only). See content formats.
editable boolean true false blocks user input. Commands and dispatch still work.
autofocus boolean | "start" | "end" false Focus the surface when it is mounted: "start" puts the caret at the start of the first block with text, "end" at the end of the last one, true where the editor starts, the start of the first block. Same as editor.focus(position).
engine "auto" | "js" | "wasm" "auto" Which engine runs the document. See engines.
host EditorHost {} Asset storage, links and errors. See host.
onCreate, onUpdate, onSelectionChange, onFocus, onBlur, onDestroy ({ editor }) => void — Listeners for the matching events.

The presets come from @gotipe/core/presets:

Preset Contents
MinimalPreset Paragraph, bold, italic, history
DefaultPreset Paragraphs, headings, bullet, numbered and to-do lists, code blocks, images, quotes, callouts, dividers, tables, toggles; bold, italic, underline, strikethrough, inline code, links, highlight, text colour; history, placeholder, slash commands
FullPreset DefaultPreset plus columns, embeds, math, files, superscript and subscript

Next steps