Skip to content
Edit on GitHub

DOCX export

Write a document as a Word file with GoTipe's own OOXML renderer, in the browser or in Node.

@gotipe/export@gotipe/export-wasmMIT

exportToDocx writes an Office Open XML document (.docx) with GoTipe's own renderer: paragraphs, headings with Word heading styles, lists, tables, links and embedded images. It runs in the same optional WebAssembly module as PDF export, loaded on the first call. Use it when people need to keep editing the document in Word or a compatible editor; use PDF when the layout must not change.

Install

npm install @gotipe/export @gotipe/export-wasm

The bundler and CSP requirements are the same as for PDF: emit the .wasm file, serve it as application/wasm, and allow 'wasm-unsafe-eval' in script-src.

Export a document

import type { GoTipeEditor } from "@gotipe/core";
import { exportToDocx } from "@gotipe/export";

export async function downloadDocx(editor: GoTipeEditor) {
  const bytes = await exportToDocx(editor, {
    title: "Quarterly report",
    author: "Finance team",
    description: "Q3 figures and commentary",
    resolveImage: async (source) => {
      const response = await fetch(source);
      if (!response.ok) throw new Error(`${source}: HTTP ${response.status}`);
      return new Uint8Array(await response.arrayBuffer());
    },
  });
  const type = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
  const url = URL.createObjectURL(new Blob([bytes], { type }));
  const link = document.createElement("a");
  link.href = url;
  link.download = "report.docx";
  link.click();
  setTimeout(() => URL.revokeObjectURL(url), 1000);
}

Options

Option Type Default Description
title string "" Document title in the file's properties.
author string "" Creator in the file's properties.
description string "" Description in the file's properties.
resolveImage (source: string) => Promise<Uint8Array | Blob> — Returns the bytes of an image URL. Required when the document has images that are not data: URLs.

Images follow the same rules as in PDF: data: images are embedded as they are, other sources go through resolveImage once per export, and PNG, JPEG, GIF and WebP are accepted with the same size limits (10 MiB per image, 64 MiB per export). An image placeholder without a source exports as nothing, or as its caption. Option names other than these throw a TypeError before anything loads.

What the file contains

GoTipe Word
Paragraph Paragraph
Heading 1–6 Paragraph with the built-in style "heading 1"…"heading 6" (outline level, navigation pane), bold, 22 pt down to 12 pt
Bold, italic, underline, strikethrough, superscript, subscript Run formatting
Text color, highlight Font color, shading
Inline code, code block Runs in "DejaVu Sans Mono"; a code block keeps its line breaks and tabs
Link External hyperlink; the text keeps the surrounding style
Bulleted, numbered and task lists Paragraphs with a text marker (•, 3., ☐, ☑), indented 0.25 in per level
Quote Paragraph; blocks inside it are indented
Callout, toggle Paragraph followed by its blocks (no box; toggles open)
Table Word table with column spans
Image Inline picture (converted to PNG), up to 560 px wide, alt as its description; the caption as the next paragraph
File, embed The file name, or the URL without one; a hyperlink when the URL is absolute, or a link to a bookmark when it is # and the ID of a block in the document (see Links). Empty placeholders are left out
Columns The columns one after another
Divider A line of box-drawing characters
Math, raw Markdown Their source text

Pages are A4 with 1 in margins. Fonts are not embedded: Word uses its default font for text and substitutes "DejaVu Sans Mono" when it is not installed.

Errors

As with PDF, invalid option names throw a TypeError and every other failure rejects with an ExportError whose code names the cause (see PDF errors), for example ENCODING_ERROR with Encoding error: Text contains an invalid XML character for a control character in the text.

Limitations

Note:

The DOCX file keeps the content and its structure, not the editor's look. There is no DOCX import.

  • No page size, margin, header, footer, table of contents or bookmark options.
  • List markers are text, so Word does not treat the paragraphs as a numbered list. Tables have no borders or table style. Columns are not laid out side by side.
  • A table cell that spans rows fails the export.
  • Unknown block types and marks fail. The link rule of PDF applies: absolute http(s) and mailto: addresses become hyperlinks, #<block ID> a link to a bookmark at that block; relative paths, unknown fragments, inline data: files and other schemes stay text.
  • Math stays as its literal source; it is not converted to Word equations.