DOCX to Markdown

Use @docx-editor.dev/docx-to-markdown to convert DOCX files to Markdown. The result includes the body, pages, headers, footers, comments, and tracked changes.

Try the DOCX to Markdown demo or read the Markdown export guide.

Before you begin

For Node.js, use version 20.16.0 or later in the 20.x release line, or version 22.3.0 or later. The converter requires WebAssembly and uses bundled fonts by default.

Install the package

npm install @docx-editor.dev/docx-to-markdown @docx-editor.dev/core

@docx-editor.dev/core is a required peer dependency. Install a version that satisfies the converter's peer dependency range and commit your lockfile.

Convert a DOCX file

The following example reads a local file in Node.js:

import { readFile } from 'node:fs/promises';
import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';

const docxBytes = await readFile('document.docx');
const result = await exportMarkdown(docxBytes);
console.log(result.markdown);

Include images

Set images: true to include image links and extracted bytes:

const result = await exportMarkdown(docxBytes, { images: true });

result.media contains image bytes and their page occurrences. See image workflows to save a folder, download a ZIP, or return hosted URLs.

Preserve displayed image sizes

Use images: { syntax: 'html' } to include displayed sizes in generated <img> tags. Dimensions use whole CSS pixels. Configure your renderer to allow sanitized HTML and retain width and height. The default Markdown syntax has no size attributes.

For custom previews, use displayWidthPx and displayHeightPx. Asset pixelWidth and pixelHeight describe the image file. The converter omits crop, rotation, and floating text wrapping. See Preserve displayed image sizes.

Read page output

The document layout engine calculates page breaks.

for (const page of result.pages) {
  console.log(page.number, page.markdown);
  console.log(page.headerMarkdown, page.footerMarkdown);
}

result.markdown contains continuous document text without page separators. Use it for an unpaged .md download. Headers and footers stay in result.pages.

For search and AI ingestion, use { displayMode: 'proposed' } to show pending insertions and hide pending deletions. The default, 'all-markup', shows both.

Configure fonts for accurate layout

Fonts determine line wrapping, table row heights, and the page boundaries in result.pages. Markdown does not preserve the DOCX font family, but the converter needs font measurements to calculate layout.

Start with the bundled substitutes for common document fonts. Use fonts to supply the author's licensed fonts or override a substitute. Use fallbackFonts: googleFonts() to load missing faces from Google Fonts; it requires network access and does not override faces already resolved by earlier sources.

See font setup and troubleshooting for runnable examples, resolution reports, and guidance on matching page references to the source document.

Runtime and output

For Next.js, use the Node.js runtime and server package configuration. Edge runtimes are not supported.

Page breaks depend on fonts, document features, and revision mode; they can differ from the application that created the document. Store the document version with page citations. result.warnings reports omitted content and font problems. Images are omitted unless enabled. See output limits before using the output as a complete transcription.

The package uses the Apache 2.0 license, including comment and tracked-change extraction. Bundled fonts retain their own open-source licenses.

Next steps

• Configure fonts and troubleshoot page layout.
• Include and deliver images.
• Connect the converter to your application.
• Review export options and result fields.