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.
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-dompnpm add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-domyarn add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-dombun add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-domExample
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" />
</>
);
}The Markdown session
- Loading.
markdownis parsed when the editor is created. Later, a value that differs from the last draftPageEditoremitted replaces the document as an external change: block ids are reused, focus, caret and scroll stay, and the replacement is one undo step. - Saving.
onChangereceives the whole file after edits, at most once per animation frame and only when the text changed. Debounce writes yourself. - Title. A leading
# headingis the page title. If the file has none, an empty title line showstitlePlaceholderand 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](andTIP,IMPORTANT,WARNING,CAUTION) a callout, a paragraph with onlyan 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 |
( |
— | 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. |
title |
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/). |
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?: React |
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 |
( |
— | Called once per editor, when it exists. A new function on a later render is not called. |
onError |
( |
— | Every editor error, like host.onError, and the failed creation of the editor (Host). |
status |
boolean | Status |
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( |
Focus the page, optionally at "start" or "end". |
insert |
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
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,tooloruser, with a colour. - A proposal is a list of anchored edits:
before + quote + afterin the file, replaced bytext. 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
onAccepta proposal is applied locally andonChangegets the new text; withoutonRejectit is hidden locally. Accept all goes one by one in document order and stops at the first stale proposal orfalseresult;onAcceptAllreplaces 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. UseBlockEditorwith the WASM engine for collaboration. - The AI command bar is off, and the extensions cannot be changed;
blocksonly filters the/menu. titleLevelchanges the title only: a# headingfurther down the file is still anh1.
Related
- Block editor · Menus · Markdown
- Model edits · Host · Security