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.
| Format | Extensions | Notes |
|---|---|---|
| DOCX | .docx | Full fidelity, and the only format whose untouched content exports back as the original bytes |
| ODT | .odt | LibreOffice, OpenOffice, and Google Docs exports: formatting, lists, tables, images, footnotes, headers and footers, comments, tracked changes |
| RTF | .rtf | Word, WordPad, TextEdit, and LibreOffice: formatting, lists, tables, images, footnotes, headers and footers, comments, tracked changes |
| Markdown | .md, .markdown | Headings, lists, tables, code, emphasis, links |
| Plain text | .txt | Paragraphs split on blank lines |
| HTML | .html, .htm | Headings, lists, tables, links, inline formatting |
<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:
- An explicit
formaton the document input. - The filename extension, when the source is a
File. - The MIME type, when the source is a
Blobthat carries one. - 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:
<ReviseEditor
initialDocuments={[
{
id: "draft",
source: new Blob([markdownString]),
format: "markdown",
title: "Draft",
},
]}
/>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:
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" });| Format | Notes |
|---|---|
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. |
pdf | Paginated like the editor, fonts embedded. Browser only. |
html | A standalone page with styles. |
markdown | Headings, lists, tables, links, code, and math. |
txt | Plain 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:
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.
Links in exported files#
A document keeps whatever link targets it was given: Markdown, HTML, and DOCX imports and agent edits store them as written. On export:
| Target | DOCX, PDF, Markdown | HTML |
|---|---|---|
http:, https:, mailto:, tel:, relative paths, #fragments | Written as links | Written as links |
Other schemes (ftp:, zotero:, obsidian:, …) | Written as links | Text only |
javascript:, vbscript:, livescript:, data: | Text only | Text 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.