Skip to content
Edit on GitHub

Page editor

PageEditor edits a Markdown file in the block editor and gives Markdown back, keeping untouched blocks byte for byte, with an optional review layer.

@gotipe/block-editor@gotipe/markdown@gotipe/suggestionsCommercial

PageEditor is BlockEditor with a Markdown session: you pass the file's text and get Markdown back after each edit. An unchanged file comes back byte for byte, and an edit rewrites only the blocks it touched. On top it can show anchored suggestions, comments and cursors from a model or a reviewer.

PageEditor always runs on the JS engine: no WebAssembly, no eval, so it works under script-src 'self'. Files, saving, names and permissions stay in your application.

Install

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

Example

MarkdownPage.tsx
import "@gotipe/theme/base.css";
import "@gotipe/theme/theme.css";
import { PageEditor, type PageEditorHandle } from "@gotipe/block-editor";
import { useEffect, useRef, useState } from "react";

export function MarkdownPage({ file, save }: { file: string; save: (text: string) => void }) {
  const page = useRef<PageEditorHandle>(null);
  const [draft, setDraft] = useState(file);

  // Save one second after the last edit.
  useEffect(() => {
    if (draft === file) return;
    const timer = setTimeout(() => save(draft), 1000);
    return () => clearTimeout(timer);
  }, [draft, file, save]);

  return (
    <>
      <button type="button" onClick={() => page.current?.selectTitle()}>Rename</button>
      <PageEditor ref={page} markdown={file} onChange={setDraft} titlePlaceholder="notes.md" />
    </>
  );
}
Live editorMarkdown follows
Loading the editor…

The Markdown session

  • Loading. markdown is parsed when the editor is created. Later, a value that differs from the last draft PageEditor emitted replaces the document as an external change: block ids are reused, focus, caret and scroll stay, and the replacement is one undo step.
  • Saving. onChange receives the whole file after edits, at most once per animation frame and only when the text changed. Debounce writes yourself.
  • Title. A leading # heading is the page title. If the file has none, an empty title line shows titlePlaceholder and stays out of the file until someone types a title.
  • Kept as is. Front matter is not shown and is written back unchanged. HTML, footnotes, link definitions, quotes that hold more than one paragraph, list items that hold more than a paragraph and nested lists, lists that mix tasks and plain items, and numbered task lists appear as read-only "Markdown" blocks with a lock.
  • Mapped blocks. - [ ] is a task, > [!NOTE] (and TIP, IMPORTANT, WARNING, CAUTION) a callout, a paragraph with only ![alt](src "caption") an image, and a paragraph with only a relative link named after its file, such as [report.pdf](assets/report.pdf), a file block.
  • Table column types are not stored: Number is right alignment (---:), Code wraps cells in backticks, Yes / no writes ✓ and — in every UI language. A column of the words an earlier version wrote there (yes, да) still reads as Yes / no.

Details of the codec are in Markdown.

Props

Prop Type Default Description
markdown string — The file's text. A new value that differs from the last draft replaces the document.
onChange (markdown: string) => void — The draft after edits.
readOnly boolean false No input; links open on a plain click; task boxes are disabled.
host EditorHost — Assets, links and errors; see below.
locale string "en" UI language; "ru" is built in.
i18n I18n — A ready dictionary from createI18n; wins over locale.
titlePlaceholder string "Untitled" Shown in an empty title, for example the file name.
titleLevel 1 | 2 | 3 | 4 | 5 | 6 1 The HTML level of the title: h1 by default. It looks the same at any level; pass 2 when your page has its own h1. Other headings of the file keep their levels.
view "notion" | "docs" | "modern" | "minimal" "notion" One of the shared views.
highlight CodeHighlighter — Code highlighter (@gotipe/block-editor/shiki).
blockViews BlockViews — Your views; they win over the page's and the shared ones.
blocks PageBlockKind[] all Blocks offered by /.
review PageReviewProps — Suggestions, comments and cursors. Without it there is no review layer.
reviewBar { title?: ReactNode; extra?: ReactNode[] } | false not shown Pass an object to show the review bar above the page.
autoFocus boolean — Put the caret at the end once the editor exists.
onReady (editor: GoTipeEditor) => void — Called once per editor, when it exists. A new function on a later render is not called.
onError (error: GoTipeError) => void — Every editor error, like host.onError, and the failed creation of the editor (Host).
status boolean | StatusLineOptions false Words and characters under the page (counter line). The page has FindReplace and CharacterCount, so Mod+F opens the find bar.
className, style — On the root .gotipe-page.

markdown and readOnly apply at any time; host is read on each call. The extensions are fixed: pageExtensions() (exported) lists them. Toggles, columns, embeds and math are not among them.

Ref

Member Description
editor The GoTipeEditor, or null before it exists.
getMarkdown() The current document as Markdown.
focus(position?) Focus the page, optionally at "start" or "end".
insertBlock(kind) Insert a block of a PageBlockKind at the caret, for your own toolbar.
getTitle() Text of the leading # heading, or null when there is none or it is empty.
selectTitle() Focus the title and select its text.
review The review actions below, or null without review.

PageBlockKind is one of text, heading1, heading2, heading3, bulletList, orderedList, todoList, quote, code, table, divider, callout, image, file. The / menu groups them as Style, Insert and Upload.

Host

host takes the EditorHost callbacks. Without saveAsset, pasted and uploaded images and files up to 10 MiB are stored in the file as data: URLs. Without openLink, a link opens in a new tab with noopener. Without onError and host.onError, errors show as a toast; with either of them the toast is off.

When the editor cannot be created — the Markdown cannot be read or the document fails its check — the page shows "The document could not be opened" in place of the loading shape, and the failure goes once to onError and host.onError as a GoTipeError; a reason that is not one becomes EDITOR_NOT_INITIALIZED with the reason as details.cause. Without either of them it is logged to the console. A creation that fails after the page is gone reports nothing. Show the same markdown again in a new PageEditor (a new key) to try again.

Review layer

ReviewedPage.tsx
import { PageEditor, type PageReviewProps } from "@gotipe/block-editor";

const review: PageReviewProps = {
  lanes: [{ id: "assistant", name: "Assistant", kind: "agent", color: "var(--gt-track-1)" }],
  proposals: [
    {
      id: "p1",
      laneId: "assistant",
      reason: "Shorter wording",
      edits: [{ before: "Run ", quote: "the whole build", after: " first.", text: "the build" }],
    },
  ],
};

export function ReviewedPage({ file, save }: { file: string; save: (text: string) => void }) {
  return <PageEditor markdown={file} onChange={save} review={review} reviewBar={{ title: "Assistant" }} />;
}
  • A lane is who suggests: agent, skill, tool or user, with a colour.
  • A proposal is a list of anchored edits: before + quote + after in the file, replaced by text. Anchors are matched against the draft after every edit. Anything other than exactly one match makes the proposal stale: it can only be rejected.
  • Without onAccept a proposal is applied locally and onChange gets the new text; without onReject it is hidden locally. Accept all goes one by one in document order and stops at the first stale proposal or false result; onAcceptAll replaces that.
  • Comments quote a range, can be questions, and take replies through onReply.
  • Cursors stand at the end of a proposal's text or at an anchor, with a label.
  • On a page at least 880 px wide (card, gap and minimum page width tokens) cards stand in the margin beside their text; on a narrower page a card opens next to the text you click. Escape closes it.

ref.current.review has accept(id), reject(id), acceptAll(), rejectAll(), states() and focus(id). ReviewBar and LaneAvatars are exported for a bar of your own. The data model and callbacks are described in model edits.

Language and read-only

locale="ru" switches the UI to Russian; i18n takes any dictionary (see i18n). PageEditor sets its own provider, so a surrounding GoTipeI18nProvider does not reach it. With readOnly the page ignores input, hides the handle and menus, and opens links on a plain click.

Limitations

  • There is no CRDT collaboration inside PageEditor: it always uses the JS engine. Use BlockEditor with the WASM engine for collaboration.
  • The AI command bar is off, and the extensions cannot be changed; blocks only filters the / menu.
  • titleLevel changes the title only: a # heading further down the file is still an h1.