|
| 1 | +--- |
| 2 | +title: Export to docx (Office Open XML) |
| 3 | +description: Export BlockNote documents to a docx word (Office Open XML) file. |
| 4 | +imageTitle: Export to docx |
| 5 | +path: /docs/export-to-docx |
| 6 | +--- |
| 7 | + |
| 8 | +import { Example } from "@/components/example"; |
| 9 | +import { Callout } from "nextra/components"; |
| 10 | + |
| 11 | +# Exporting blocks to docx |
| 12 | + |
| 13 | +It's possible to export BlockNote documents to docx, completely client-side. |
| 14 | + |
| 15 | +<Callout type={"info"}> |
| 16 | + This feature is provided by the `@blocknote/xl-docx-exporter`. `xl-` packages |
| 17 | + are fully open source, but released under a copyleft license. A commercial |
| 18 | + license for usage in closed source, proprietary products comes as part of the |
| 19 | + [Business subscription](/pricing). |
| 20 | +</Callout> |
| 21 | + |
| 22 | +First, install the `@blocknote/xl-docx-exporter` and `docx` packages: |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install @blocknote/xl-docx-exporter docx |
| 26 | +``` |
| 27 | + |
| 28 | +Then, create an instance of the `DOCXExporter` class. This exposes the following methods: |
| 29 | + |
| 30 | +```typescript |
| 31 | +import { |
| 32 | + DOCXExporter, |
| 33 | + docxDefaultSchemaMappings, |
| 34 | +} from "@blocknote/xl-docx-exporter"; |
| 35 | +import { Packer } from "docx"; |
| 36 | + |
| 37 | +// Create the exporter |
| 38 | +const exporter = new DOCXExporter(editor.schema, docxDefaultSchemaMappings); |
| 39 | + |
| 40 | +// Convert the blocks to a docxjs document |
| 41 | +const docxDocument = await exporter.toDocxJsDocument(editor.document); |
| 42 | + |
| 43 | +// Use docx to write to file: |
| 44 | +await Packer.toBuffer(docxDocument); |
| 45 | +``` |
| 46 | + |
| 47 | +See the [full example](/examples/interoperability/converting-blocks-to-docx) below: |
| 48 | + |
| 49 | +<Example name="interoperability/converting-blocks-to-docx" /> |
| 50 | + |
| 51 | +### Customizing the Docx output file |
| 52 | + |
| 53 | +`toDocxJsDocument` takes an optional `options` parameter, which allows you to customize document metadata (like the author) and section options (like headers and footers). |
| 54 | + |
| 55 | +Example usage: |
| 56 | + |
| 57 | +```typescript |
| 58 | +import { Paragraph, TextRun } from "docx"; |
| 59 | + |
| 60 | +const doc = await exporter.toDocxJsDocument(testDocument, { |
| 61 | + documentOptions: { |
| 62 | + creator: "John Doe", |
| 63 | + }, |
| 64 | + sectionOptions: { |
| 65 | + headers: { |
| 66 | + default: { |
| 67 | + options: { |
| 68 | + children: [new Paragraph({ children: [new TextRun("Header")] })], |
| 69 | + }, |
| 70 | + }, |
| 71 | + }, |
| 72 | + footers: { |
| 73 | + default: { |
| 74 | + options: { |
| 75 | + children: [new Paragraph({ children: [new TextRun("Footer")] })], |
| 76 | + }, |
| 77 | + }, |
| 78 | + }, |
| 79 | + }, |
| 80 | +}); |
| 81 | +``` |
| 82 | + |
| 83 | +### Custom mappings / custom schemas |
| 84 | + |
| 85 | +The `DOCXExporter` constructor takes a `schema`, `mappings` and `options` parameter. |
| 86 | +A _mapping_ defines how to convert a BlockNote schema element (a Block, Inline Content, or Style) to a [docxjs](https://docx.js.org/) element. |
| 87 | +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 docx, you can pass your own `mappings`: |
| 88 | + |
| 89 | +For example, use the following code in case your schema has an `extraBlock` type: |
| 90 | + |
| 91 | +```typescript |
| 92 | +import { |
| 93 | + DOCXExporter, |
| 94 | + docxDefaultSchemaMappings, |
| 95 | +} from "@blocknote/xl-docx-exporter"; |
| 96 | +import { Paragraph, TextRun } from "docx"; |
| 97 | + |
| 98 | +new DOCXExporter(schema, { |
| 99 | + blockMapping: { |
| 100 | + ...docxDefaultSchemaMappings.blockMapping, |
| 101 | + myCustomBlock: (block, exporter) => { |
| 102 | + return new Paragraph({ |
| 103 | + children: [ |
| 104 | + new TextRun({ |
| 105 | + text: "My custom block", |
| 106 | + }), |
| 107 | + ], |
| 108 | + }); |
| 109 | + }, |
| 110 | + }, |
| 111 | + inlineContentMapping: docxDefaultSchemaMappings.inlineContentMapping, |
| 112 | + styleMapping: docxDefaultSchemaMappings.styleMapping, |
| 113 | +}); |
| 114 | +``` |
| 115 | + |
| 116 | +### Exporter options |
| 117 | + |
| 118 | +The `DOCXExporter` constructor takes an optional `options` parameter. |
| 119 | +While conversion happens on the client-side, the default setup uses a server hosted proxy to resolve files: |
| 120 | + |
| 121 | +```typescript |
| 122 | +const defaultOptions = { |
| 123 | + // a function to resolve external resources in order to avoid CORS issues |
| 124 | + // by default, this calls a BlockNote hosted server-side proxy to resolve files |
| 125 | + resolveFileUrl: corsProxyResolveFileUrl, |
| 126 | + // the colors to use in the Docx for things like highlighting, background colors and font colors. |
| 127 | + colors: COLORS_DEFAULT, // defaults from @blocknote/core |
| 128 | +}; |
| 129 | +``` |
0 commit comments