feat: odt exporter (#1331)

---------

Co-authored-by: Arek Nawo <areknawo@areknawo.com>
Co-authored-by: Nick the Sick <nick@blocknotejs.org>

Author: 3 people

docs/pages/docs/editor-api/_meta.json

@@ -5,5 +5,6 @@
   "converting-blocks": "",
   "server-processing": "",
   "export-to-pdf": "",
-  "export-to-docx": ""
+  "export-to-docx": "",
+  "export-to-odt": ""
 }

docs/pages/docs/editor-api/export-to-odt.mdx

@@ -0,0 +1,104 @@
+---
+title: Export to ODT (Open Document Text)
+description: Export BlockNote documents to an ODT (Open Document Text) file.
+imageTitle: Export to ODT
+path: /docs/export-to-odt
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
+# Exporting blocks to ODT
+
+It's possible to export BlockNote documents to ODT, completely client-side.
+
+<Callout type={"info"}>
+  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](/pricing).
+</Callout>
+
+First, install the `@blocknote/xl-odt-exporter` package:
+
+```bash
+npm install @blocknote/xl-odt-exporter
+```
+
+Then, create an instance of the `ODTExporter` class. This exposes the following methods:
+
+```typescript
+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](/examples/interoperability/converting-blocks-to-odt) below:
+
+<Example name="interoperability/converting-blocks-to-odt" />
+
+### Customizing the ODT output file
+
+`toODTDocument` takes an optional `options` parameter, which allows you to customize different options (like headers and footers).
+
+Example usage:
+
+```typescript
+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](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part3-schema/OpenDocument-v1.3-os-part3-schema.html) XML element.
+If you're using a [custom schema](/docs/custom-schemas) 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:
+
+```tsx
+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,
+});
+```
+
+### 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:
+
+```typescript
+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 colors to use in the ODT for things like highlighting, background colors and font colors.
+  colors: COLORS_DEFAULT, // defaults from @blocknote/core
+};
+```

examples/05-interoperability/05-converting-blocks-to-pdf/App.tsx

@@ -8,9 +8,9 @@ import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
 import {
+  SuggestionMenuController,
   getDefaultReactSlashMenuItems,
   getPageBreakReactSlashMenuItems,
-  SuggestionMenuController,
   useCreateBlockNote,
 } from "@blocknote/react";
 import {
@@ -35,7 +35,7 @@ export default function App() {
         content: [
           {
             type: "text",
-            text: "Welcome to this",
+            text: "Welcome to this ",
             styles: {
               italic: true,
             },

examples/05-interoperability/06-converting-blocks-to-docx/App.tsx

@@ -8,9 +8,9 @@ import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
 import {
+  SuggestionMenuController,
   getDefaultReactSlashMenuItems,
   getPageBreakReactSlashMenuItems,
-  SuggestionMenuController,
   useCreateBlockNote,
 } from "@blocknote/react";
 import {
@@ -31,7 +31,7 @@ export default function App() {
         content: [
           {
             type: "text",
-            text: "Welcome to this",
+            text: "Welcome to this ",
             styles: {
               italic: true,
             },

examples/05-interoperability/07-converting-blocks-to-odt/.bnexample.json

@@ -0,0 +1,10 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "areknawo",
+  "tags": [""],
+  "dependencies": {
+    "@blocknote/xl-odt-exporter": "latest"
+  },
+  "pro": true
+}