Word to Markdown

Word to Markdown (DOCX → Markdown converter)

Convert Word documents to beautiful Markdown. Via command line, as a Node library, or in your browser. An even better version of the original word-to-markdown.

Try it in your browser at word2md.com, or use it from the command line — no clone required:

npx word-to-markdown input.docx > output.md

What it converts

• Paragraphs and line breaks
• Headings
• Bold, italic, and strikethrough
• Superscript and subscript — preserved as inline / tags
• Bullet lists, and numbered lists (kept as 1./2./3. by default)
• Nested lists
• Tables
• Links
• Footnotes and endnotes — converted to GFM/Pandoc [^1] footnotes
• Images — embedded inline as base64 data URIs, or extracted to files
• Equations — converted to LaTeX: inline $…$, or a $$ block for an equation on its own line

Notes and limitations

• Numbered lists are kept as 1./2./3. ordered lists, numbered as Word numbers them, so a list interrupted by a paragraph, table, or another list continues where it left off. Pass { numberedLists: 'bullets' } (library) or --bullet-lists (CLI) to convert them to bullet lists instead (matching the original word-to-markdown). Outline numbering that repeats the parent's number, like contracts' 1. → 1.1, 1.2, is written out as text (## 1. Scope, 1.1 Purpose), since Markdown lists can't show it.
• Images are inlined as base64 data URIs by default. To extract them to files with relative links instead, use { images: 'extract' } (library — the bytes come back on ConvertResult.images) or --image-dir (CLI). Drop them entirely with { images: 'strip' } / --strip-images. On the web, documents with images offer a Download .zip (Markdown + an images/ folder). For full control, pass a custom Mammoth image handler via options.mammoth.
• Underline is dropped by default (Mammoth's default, since underlines are easily confused with links). Pass { underline: 'preserve' } (library) or --underline (CLI) to keep it as an inline tag.
• Curly quotes (“ ” ‘ ’) are kept when the text is mostly Chinese, where they are the Chinese quotation marks, and converted to ASCII everywhere else. Word writes the same code points for English curly quotes, so a quote can't be classified on its own. Pass { quotes: 'ascii' } (library) or --quotes ascii (CLI) to always convert, or 'preserve' / --quotes preserve to always keep them.
• Footnotes and endnotes become standard GFM/Pandoc footnotes — a [^1] reference in the body and a [^1]: … definition at the end — which render on GitHub and in the web preview. Pass { footnotes: 'preserve' } (library) or --preserve-footnotes (CLI) to instead keep Mammoth's raw links and numbered note list (useful for CommonMark targets that lack footnote support). Notes whose bodies span multiple paragraphs are converted with indented continuation paragraphs.
• Text boxes are converted as paragraphs after the containing paragraph. A text box saved without Word's VML fallback (as some other tools write them) is dropped, and convertWithWarnings warns.
• Comments are dropped during the .docx → HTML step, and convertWithWarnings warns with how many had text. To keep them, map them in a Mammoth style map, e.g. { mammoth: { styleMap: ['comment-reference => sup'] } }.
• Headers and footers are dropped. convertWithWarnings warns when one has text beyond a page number.
• Equations (Office Math) become LaTeX: inline $…$, or a $$…$$ block when the equation is on its own line, which GitHub and most Markdown math renderers (KaTeX, MathJax) display. Fractions, scripts, roots, sums and integrals, brackets, functions and limits, accents, and matrices are converted. Pass { equations: 'strip' } (library) or --strip-equations (CLI) to drop them instead, with a convertWithWarnings warning.
• Heading levels come from Word's paragraph styles, not from font size.

How is this different from the original?

_TL;DR: This project is a complete rewrite, using modern tools and libraries, and is much faster and more reliable. The output should be the same or better. Feedback welcome!_

A note on privacy

Word to Markdown is designed with privacy as a core principle. The application operates entirely client-side:

• Complete client-side processing: When using the web interface, all document conversion happens locally in your browser using JavaScript. Your documents never leave your computer.
• No server uploads: When using the web interface, files are processed entirely on your device. No document content is ever transmitted to any server.
• No personal data collection: The application does not collect, store, or transmit any personal information or document contents.
• Privacy-first analytics: The hosted version at word2md.com uses only privacy-centric Cloudflare Analytics for anonymous usage statistics. No Google Analytics or user tracking.
• Self-hosting option: For maximum privacy, you can run the application locally or self-host it without any analytics whatsoever.

Whether you use the command line tool, run it locally in your browser, or use the hosted version, your documents and privacy are protected.

Command line

Run it directly with npx (downloads and runs the latest published version):

npx word-to-markdown path/to/your/file.docx > output.md

Or install it globally to get the w2m command:

npm install -g word-to-markdown

w2m path/to/your/file.docx > output.md

The converted Markdown is written to stdout and any document warnings (encryption, sensitivity labels, and the like) to stderr, so a redirect captures only the Markdown. The command exits with status 1 and a friendly message if the file is missing, unreadable, or not a valid .docx. Only .docx is supported — re-save older .doc files as .docx first.

To read the document from stdin, pass - as the file, or leave it out and pipe the file in:

cat report.docx | w2m > report.md

curl -sL https://example.com/report.docx | w2m - -o report.md

Options:

• -o, --output — write the Markdown to instead of stdout (warnings still go to stderr). -o - means stdout.
• --bullet-lists — convert numbered lists to bullets instead of keeping 1./2./3..
• --underline — preserve underlined text as inline tags (dropped by default).
• --strip-images — remove images instead of embedding them as base64 data URIs.
• --image-dir — extract images to and link them relatively, instead of embedding base64. Links resolve relative to where you save the Markdown, e.g. w2m --image-dir images report.docx > report.md, or with -o, w2m -o out/report.md --image-dir images report.docx (images land in out/images/).
• --preserve-footnotes — keep Word footnotes as raw links and a numbered note list instead of GFM [^1] footnotes.
• --strip-equations — drop Word equations instead of converting them to LaTeX.
• --quotes — how to treat curly quotes: auto (default) keeps them in mostly-Chinese text, ascii converts them everywhere, preserve keeps them everywhere.
• -q, --quiet — print nothing to stderr except errors: no warnings and no "Wrote …" notes.
• --strict — exit with status 2 if the document has warnings, so a script can tell "converted, but check it" (2) from "failed" (1). The Markdown is still written. Combine with --quiet to rely on the exit status alone.
• --verbose — On failure, also print the underlying error and stack trace.
• -V, --version — print the version.

MCP server

w2m mcp runs a local Model Context Protocol server on stdio, so AI agents can convert .docx files on your machine. Like the website, it never uploads anything: the agent passes a file path, and the server reads and converts the file locally.

In Claude Desktop, it's one click: download word-to-markdown.mcpb and double-click it. Claude Desktop installs it as an extension. You don't need Node or a terminal, since Claude Desktop includes Node.

Add it to Claude Code:

claude mcp add word-to-markdown -- npx -y word-to-markdown mcp

Or to any MCP client that takes a JSON config:

{

"mcpServers": { "word-to-markdown": { "command": "npx", "args": ["-y", "word-to-markdown", "mcp"] } } }

It has one tool, convert_docx_to_markdown:

• path (required): the .docx to convert. Prefer an absolute path; relative paths resolve against the server's working directory.
• output_path: write the Markdown to this .md (or .markdown) file instead of returning it, which is handy for long documents. The tool won't write through a symlink.
• image_dir: extract images into this folder and link them. It must be a relative folder inside output_path's folder (or the .docx's). By default images are dropped, because base64 images would flood the agent's context.
• overwrite: replace output_path or image files that already exist. Off by default, so the tool refuses rather than clobbering a file. That matters when an agent is acting on instructions it read in a document.
• bullet_lists, preserve_footnotes: same as the CLI flags.

It returns the Markdown and any document warnings, also as structured content.

In the browser, word2md.com registers the same conversion as WebMCP tools (convert_docx_to_markdown, taking the file as base64, and get_converted_markdown) for agents in browsers that support it. They run in the tab, just like dropping a file.

Use as a library

Published to npm as word-to-markdown. It ships as an ES module with TypeScript declarations and requires Node 22.13 or later.

npm install word-to-markdown

import convert, { convertWithWarnings } from 'word-to-markdown';

// Just the Markdown: const markdown = await convert('path/to/your/file.docx');

// Markdown plus any document warnings (e.g. encryption, sensitivity labels): const { markdown, warnings } = await convertWithWarnings( 'path/to/your/file.docx', );

Both functions accept either a file-path string (Node) or an ArrayBuffer (Node or the browser):

const { markdown } = await convertWithWarnings(arrayBuffer);

API

• `convert(input, options?): Promise ` — resolves to the Markdown.
• `convertWithWarnings(input, options?): Promise<{ markdown: string; warnings: string[]; warningDetails: WarningDetail[]; images? }>` — also returns human-readable warnings for encrypted, protected, or sensitivity-labeled documents and for dropped content, and (in extract mode) the extracted images. warningDetails has one { kind, message, detail? } entry per warning, where kind is encrypted, `sensi