// the find
benbalter/word-to-markdown-js
Convert Word documents to beautiful Markdown. Via command line or in your browser.
A TypeScript rewrite of benbalter's decade-old Ruby gem that converts .docx files to Markdown. The core pipeline is Mammoth.js → Turndown → Markdownlint, which runs entirely client-side in the browser or via CLI. Useful for anyone migrating Word-heavy documentation workflows to Markdown-based systems.
The dependency choices are solid — Mammoth.js is the right tool for .docx parsing and is actively maintained, unlike the old LibreOffice shelling approach. Client-side processing is a genuine differentiator for sensitive documents; nothing leaves the browser. The fixture-based test suite with real .docx files catches format-specific regressions that pure unit tests would miss. The project is well-structured for a frontend tool: Astro for the site, a Cloudflare Worker for edge routing, Docker Compose for self-hosting.
Heading level inference from font size is explicitly unimplemented, which means heading structure in the output depends entirely on Word's semantic heading styles being used correctly — real-world Word docs often aren't. Complex layout elements (multi-column, text boxes, embedded objects) will degrade silently into flat text with no warning. The CLI is thin wrapper with no batch processing or directory support. At 226 stars for a rewrite of a tool with an established audience, adoption has been slow, which suggests the original Ruby gem's ecosystem hasn't meaningfully migrated over.