Mammoth.js

Mammoth.js converts Word .docx documents — including those authored in Microsoft Word, Google Docs, and LibreOffice — into clean, semantic HTML rather than a pixel-perfect copy of the original formatting. It leans on the document’s semantic styles, mapping a paragraph styled as “Heading 1” to an h1 element instead of trying to reproduce fonts, sizes, and colors, which keeps the generated markup simple and predictable.

The library runs in both Node.js and the browser and ships with a CLI, a promise-based API, and a small style-map DSL that lets you customize how your own document styles translate to HTML. It supports headings, lists, tables, footnotes, images, links, comments, and common inline formatting, making it a practical tool for ingesting Word content into web applications and content pipelines.

What You Get

• A promise-based convertToHtml / convertToMarkdown / extractRawText API for Node.js and the browser
• A mammoth CLI for converting documents and exporting images to a directory
• A customizable style-map DSL for mapping your own Word styles to specific HTML elements and classes
• Support for headings, lists, tables, footnotes, endnotes, images, links, comments, and inline formatting
• Pluggable image converters for controlling how embedded images are emitted (inline data URIs or external files)

Common Use Cases

• Importing Word documents authored by non-technical users into a CMS or web application
• Building content pipelines that normalize .docx uploads into semantic HTML
• Extracting raw text from Word documents for search indexing or analysis
• Mapping bespoke corporate Word styles to a consistent set of HTML components

Under The Hood

Architecture

Mammoth is organized as a clean multi-stage pipeline centered on lib/index.js, which orchestrates conversion via convert(). Input is opened with lib/unzip.js (a .docx is a zip archive), then lib/docx/docx-reader.js and its collaborators — body-reader.js, document-xml-reader.js, notes-reader.js, styles-reader.js, numbering-xml.js, and relationships-reader.js — parse the OOXML parts into an internal document model defined in lib/documents.js. The parsed document is then handed to DocumentConverter in lib/document-to-html.js, which applies the resolved style map and emits output through pluggable writers in lib/writers/ (HTML or Markdown). Style mappings are parsed by lib/style-reader.js using the lop parser-combinator DSL, and results/warnings flow through a Result monad in lib/results.js that threads conversion messages alongside values.

Tech Stack

Written in JavaScript (99.5% of the repo) targeting Node.js >=12. Core runtime dependencies include @xmldom/xmldom for XML parsing, jszip for reading the zip container, bluebird for promises, lop for the style-map grammar, underscore for utilities, argparse for the CLI, plus base64-js, dingbat-to-unicode, path-is-absolute, and xmlbuilder. Browser builds are produced with browserify, and a browser/ directory provides browser-specific implementations of unzip.js and docx/files.js via the package’s browser field.

Code Quality

The project is well tested: 33 .tests.js suites run under Mocha with hamjest/duck matchers, covering the readers, converters, style parsing, images, and raw-text extraction. ESLint runs as a pretest step, and error handling is disciplined — rather than throwing on recoverable issues, conversions accumulate warnings through the Result type and return them alongside the output, giving callers structured feedback. A hand-written lib/index.d.ts provides TypeScript types.

API Design The public API is small and ergonomic: a handful of promise-returning functions (convertToHtml, convertToMarkdown, extractRawText) take a simple input descriptor ({path}, {buffer}, or {arrayBuffer}) and an options object. Getting started requires almost no boilerplate, while the string- or array-based styleMap option and pluggable convertImage handlers offer deep customization without complicating the common case. The README is thorough, with extensive examples and a full style-map syntax reference.