Revise Editor SDK menu

Input formats

Import DOCX, ODT, RTF, Markdown, plain text, and HTML. Export DOCX, PDF, HTML, Markdown, and text.

The SDK accepts six input formats. All of them open in the same editor with the same document model. They differ in how much of the source they preserve.

FormatExtensionsNotes
DOCX.docxFull fidelity, and the only format whose untouched content exports back as the original bytes
ODT.odtLibreOffice, OpenOffice, and Google Docs exports: formatting, lists, tables, images, footnotes, headers and footers, comments, tracked changes
RTF.rtfWord, WordPad, TextEdit, and LibreOffice: formatting, lists, tables, images, footnotes, headers and footers, comments, tracked changes
Markdown.md, .markdownHeadings, lists, tables, code, emphasis, links
Plain text.txtParagraphs split on blank lines
HTML.html, .htmHeadings, lists, tables, links, inline formatting
TSX
<ReviseEditor
  initialDocuments={[
    { id: "contract", source: docxFile },
    { id: "report", source: odtFile },
    { id: "letter", source: rtfFile },
    { id: "notes", source: markdownFile },
    { id: "brief", source: htmlFile },
  ]}
/>

Earlier versions named this field docx. That name still works; pass one or the other.

Format detection#

The SDK checks, in order:

  1. An explicit format on the document input.
  2. The filename extension, when the source is a File.
  3. The MIME type, when the source is a Blob that carries one.
  4. DOCX, as the fallback.

Set the format#

A Blob or ArrayBuffer built in memory has no filename, and its MIME type may be missing or wrong. Pass format:

TSX
<ReviseEditor
  initialDocuments={[
    {
      id: "draft",
      source: new Blob([markdownString]),
      format: "markdown",
      title: "Draft",
    },
  ]}
/>
TypeScript
await editor.documents.open({
  id: "imported",
  source: await response.blob(),
  format: "html",
});

A source with no format, filename, or MIME type is parsed as DOCX. Any other content then fails to parse. Pass format when you build the source yourself.

The MIME types recognized for the binary formats are application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX), application/vnd.oasis.opendocument.text (ODT), and application/rtf, text/rtf, application/x-rtf, or text/richtext (RTF).

Format details#

DOCX

Preserves styles, fonts, tables, images, sections, page setup, headers and footers, footnotes and endnotes, comments, and tracked changes. All of them are written back on export.

Files from other producers open too. The reader follows the package's relationships and XML namespaces rather than fixed names, so custom namespace prefixes, ISO/IEC 29500 Strict files, and parts at unusual locations all import. Such a file exports as a newly written package (fidelity.fallbackCode: "nonCanonicalSource") instead of carrying its untouched parts over byte for byte. Strict value-level fidelity, such as percentage table widths, is incomplete.

ODT

Formatting is resolved through the document's styles and applied directly to the text: fonts, sizes, colors, highlighting, bold, italic, underline, strikethrough, superscript and subscript, small caps, and letter spacing; paragraph alignment, indents, spacing, line height, borders, shading, and page breaks. Lists keep their numbering, including start values and numbering that continues across interruptions. Tables keep merged cells, column widths, and cell shading. Images, footnotes and endnotes, running headers and footers, comments, tracked insertions and deletions, and page size and margins all come in.

Floating pictures and text boxes are placed inline where they are anchored; charts and embedded objects come in as their preview image when the file carries one. Named styles are not kept as styles, only their effect.

RTF

Reads the RTF that Word ("Save as RTF"), WordPad, TextEdit, and LibreOffice write: fonts, sizes, colors, highlighting, and the full range of character formatting; paragraph alignment, indents, spacing, line spacing, borders, and shading; headings from Word's heading styles; lists from Word's list table and from WordPad's older bullet markup; tables with merged cells and column widths; PNG, JPEG, and Windows metafile pictures; hyperlinks; footnotes and endnotes; headers and footers; comments; tracked changes; and page size and margins. Text in any Windows code page or East Asian encoding decodes correctly.

Tables nested inside table cells are flattened into the outer cell, and multi-column sections import as a single column.

Markdown

Headings, lists, and tables become the matching document blocks. Markdown has no page setup or revision marks, so the document opens with default page setup and no tracked changes.

Plain text

Each block of text separated by a blank line becomes a paragraph.

HTML

Structural markup maps to document blocks. Scripts, styles, and layout CSS are ignored. <pre> becomes a code block, a table <caption> becomes a paragraph next to the table, and a <br> inside a heading stays a line break in that heading. A <br> inside a paragraph starts a new paragraph.

Titles#

Without a title, the SDK uses the filename without its extension. Master Agreement.docx becomes "Master Agreement".

Export#

tools.export() produces a file in any of five formats:

TypeScript
const docx = await editor.tools.export(); // .docx, tracked changes intact
const clean = await editor.tools.export({ format: "docx", mode: "final" });
const pdf = await editor.tools.export({ format: "pdf" });
const html = await editor.tools.export({ format: "html" });
const markdown = await editor.tools.export({ format: "markdown" });
FormatNotes
docx (default)Pending tracked changes and comments export as native Word revisions and comments. Untouched content from an imported .docx leaves as the original bytes.
pdfPaginated like the editor, fonts embedded. Browser only.
htmlA standalone page with styles.
markdownHeadings, lists, tables, links, code, and math.
txtPlain text.

Two modes decide what happens to pending changes:

  • "review" (default): a .docx keeps pending tracked changes and comments; the other formats show the text with changes accepted.
  • "final": every pending change is accepted and every comment dropped first — a clean copy to send out. In the editor, a final .docx is regenerated rather than grafted onto the original file, so none of its revisions or comments come back. On the server, a final .docx keeps the original file's bytes for content the accepted changes didn't touch.

Degraded PDF output#

A PDF needs its fonts (and, for formulas, the KaTeX fonts). If one can't load, for example because the page can't reach revise.io and the fonts are not mirrored with setAssetBaseUrl(), the export still succeeds but draws text in a substitute font that may garble or drop characters. Ask to be told, or refuse the file:

TypeScript
const pdf = await editor.tools.export({
  format: "pdf",
  onWarnings: (warnings) => console.warn(warnings), // only when degraded
});

try {
  await editor.tools.export({ format: "pdf", strict: true });
} catch (error) {
  if (error instanceof ReviseExportError) showRetry(error.warnings);
}

The same cases are reported: a font or math asset that did not load, a character the embedded fonts have no glyph for, and text shaping that is unavailable. On the server, doc.export() lists them in warnings, and strict: true throws the library's error with code export_degraded. The server engine can't draw formulas: its PDFs leave math out and say so, so a strict server export refuses any document with math.

On the server, revise/server's doc.export({ format, mode }) takes the same options, adds pdf, and reports what a .docx export kept from the original file.

A document imported from ODT, RTF, Markdown, or HTML exports as a valid .docx. ODT and RTF are import-only.

A document keeps whatever link targets it was given: Markdown, HTML, and DOCX imports and agent edits store them as written. On export:

TargetDOCX, PDF, MarkdownHTML
http:, https:, mailto:, tel:, relative paths, #fragmentsWritten as linksWritten as links
Other schemes (ftp:, zotero:, obsidian:, …)Written as linksText only
javascript:, vbscript:, livescript:, data:Text onlyText only

"Text only" means the link's text is exported without the link. Schemes are matched the way a browser reads them, so JavaScript: or java\tscript: count too. Markdown escapes the characters in a target that a Markdown reader would decode or treat as the end of the link, so it reads back as the stored target. Images follow the same rules, except that a data:image/… source is kept. RTF and ODT imports drop unsafe targets when they read the file.

Exports are data, not a security boundary. If you render exported Markdown, or display link targets from read_document or getDocument(), apply your own URL policy in that renderer. A .docx export keeps the original bytes of content you didn't touch in an imported .docx, so a hyperlink in that content keeps its original target, whatever its scheme.