BlockNote DocsFeaturesExportODT

ODT Export

It's possible to export BlockNote documents to ODT, completely client-side.

This feature is provided by the @blocknote/xl-odt-exporter. xl- packages are fully open source, but released under a copyleft license. A commercial license for usage in closed source, proprietary products comes as part of the Business subscription.

First, install the @blocknote/xl-odt-exporter package:

npm install @blocknote/xl-odt-exporter

Then, create an instance of the ODTExporter class. This exposes the following methods:

import {
  ODTExporter,
  odtDefaultSchemaMappings,
} from "@blocknote/xl-odt-exporter";

// Create the exporter
const exporter = new ODTExporter(editor.schema, odtDefaultSchemaMappings);

// Convert the blocks to a ODT document (Blob)
const odtDocument = await exporter.toODTDocument(editor.document);

See the full example below:

Customizing the ODT output file

toODTDocument takes an optional options parameter, which allows you to customize different options (like headers and footers).

Example usage:

const odt = await exporter.toODTDocument(testDocument, {
  // XML string
  footer: "<text:p>FOOTER</text:p>",
  // XMLDocument
  header: new DOMParser().parseFromString(
    `<text:p xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0">HEADER</text:p>`,
    "text/xml",
  ),
});

Custom mappings / custom schemas

The ODTExporter constructor takes a schema, mappings and options parameter. A mapping defines how to convert a BlockNote schema element (a Block, Inline Content, or Style) to the ODT XML element. If you're using a custom schema in your editor, or if you want to overwrite how default BlockNote elements are converted to ODT XML elements, you can pass your own mappings:

For example, use the following code in case your schema has an extraBlock type:

import {
  ODTExporter,
  odtDefaultSchemaMappings,
} from "@blocknote/xl-odt-exporter";

new ODTExporter(schema, {
  blockMapping: {
    ...odtDefaultSchemaMappings.blockMapping,
    myCustomBlock: (block, exporter) => {
      return <text:p>My custom block</text:p>;
    },
  },
  inlineContentMapping: odtDefaultSchemaMappings.inlineContentMapping,
  styleMapping: odtDefaultSchemaMappings.styleMapping,
});

Math & diagram blocks

The math and diagram blocks live in separate packages, and so do their ODT mappings. Spread them into the default mappings to export math as native (editable) formula objects and diagrams as embedded images:

import {
  inlineMathMapping,
  mathBlockMapping,
} from "@blocknote/math-block/odt-exporter";
import { createDiagramBlockMapping } from "@blocknote/diagram-block/odt-exporter";

const exporter = new ODTExporter(editor.schema, {
  ...odtDefaultSchemaMappings,
  blockMapping: {
    ...odtDefaultSchemaMappings.blockMapping,
    math: mathBlockMapping,
    diagram: createDiagramBlockMapping(),
  },
  inlineContentMapping: {
    ...odtDefaultSchemaMappings.inlineContentMapping,
    inlineMath: inlineMathMapping,
  },
});

Invalid LaTeX or Mermaid sources render an error placeholder with the error message, mirroring the editor.

Math exports fine server-side (the LaTeX is converted to MathML without rendering). Rendering diagrams to images, however, requires a browser — when exporting server-side, pass a renderDiagram function to createDiagramBlockMapping (e.g. backed by @mermaid-js/mermaid-cli or a Kroki server); without one, the export throws.

Exporter options

The ODTExporter constructor takes an optional options parameter. While conversion happens on the client-side, the default setup uses a server hosted proxy to resolve files:

const defaultOptions = {
  // a function to resolve external resources in order to avoid CORS issues
  // by default, this calls a BlockNote hosted server-side proxy to resolve files
  resolveFileUrl: corsProxyResolveFileUrl,
  // the strings rendered into the exported document (file link texts, error
  // placeholders); pass a locale from @blocknote/core/locales (or your
  // editor's dictionary) to export in another language
  dictionary: locales.en,
  // the colors to use in the ODT for things like highlighting, background colors and font colors.
  colors: COLORS_DEFAULT, // defaults from @blocknote/core
};

Email Export

Export BlockNote documents to an email using React Email.

Import

It's possible to import content into BlockNote.

On this page

ODT Export
Customizing the ODT output file
Custom mappings / custom schemas
Math & diagram blocks
Exporter options