A Word document turned into Markdown is only as useful as what comes along with the text: footnotes that still work, an equation you can still read, a picture still in its place. So we made one small Word file for each of nine things documents carry, and one small EPUB book, and ran them through four converters: LensUp’s DOCX to Markdown and EPUB to Markdown pages, which work in the browser, and three tools you install — Pandoc, Microsoft’s markitdown and mammoth.
The test
- Word: one DOCX per feature — a nested and a numbered list, two footnotes, a web link and an email link, two equations, an image between two paragraphs, a figure with a numbered caption, a table inside a table, a tracked insertion and deletion, and a comment. Each file was written by hand as Word’s own XML, not by any of the four tools, and each is headed SPECIMEN.
- EPUB: one EPUB 3 book with three chapters whose reading order differs from their file names, a table of contents, a footnote, an illustration with a caption, and the same ornament at the top of every chapter.
- The tools, as plainly as each runs: LensUp in Chromium on lensup.ai, keeping the ZIP it offers (the Markdown and its images); on a Mac, Pandoc 3.12.1 told to write GitHub-flavoured Markdown and to save images to a folder (
-t gfm --extract-media), and markitdown 0.1.8 and mammoth 1.13.0 with no options. mammoth reads only Word files, and its Markdown output is one its own documentation no longer recommends; its main output is HTML. - The score: one rule per feature, the same for every tool, run by a script on what each tool wrote. A picture counts as kept only when the output carries the original image itself, as a file or inside the Markdown; a footnote link counts only when it leads somewhere in the same file. The rule says what happened, not whether it is right: a dropped comment is just dropped.
Word (DOCX) to Markdown
| What the file has | LensUp | Pandoc | markitdown | mammoth |
|---|---|---|---|---|
| Lists, nested, numbered | bullets, nesting, numbers | bullets, nesting, numbers | bullets, nesting, numbers | bullets, nesting, numbers |
| Footnotes | Markdown footnotes ([^1]) | Markdown footnotes ([^1]) | numbered list at the end, links go nowhere | numbered list at the end, linked |
| Links (web and email) | both links | both links | one link of two | both links |
| Equations | LaTeX, both | LaTeX, both | lost | lost |
| An image between two paragraphs | kept (file), in place, no size | kept (file), in place, with its size | placeholder only, no image | kept, in place, as text inside the Markdown (base64), no size |
| A figure caption | kept, with its number | kept, number lost | kept, number lost | kept, number lost |
| A table inside a table | inner table folded into its cell as lines of text | both tables kept, the inner one in its cell (as HTML) | inner table spilled into its cell as raw table syntax | no table: every cell a paragraph |
| Tracked changes | accepted | accepted | accepted | accepted |
| Comments | dropped | dropped | dropped | dropped |
LensUp and Pandoc kept the most: the lists, both footnotes as Markdown footnotes, both links, both equations as LaTeX (the plain-text notation equations are typed in), and the image as a file where it was in the text. Only Pandoc also kept the size the picture had in the Word file; LensUp and mammoth wrote it without one, so it shows at the picture’s own size.
markitdown and mammoth lost both equations and wrote the footnotes as a numbered list at the end. mammoth’s footnote numbers link to that list; markitdown’s point to places that are not in its Markdown. markitdown kept the web link but turned the email link into plain text, and put a placeholder with no image where the picture was. mammoth kept the picture in place, written into the Markdown itself as text-encoded image data (base64): a bigger file, but no image folder to carry.
Only LensUp kept the caption’s number, «Figure 1»; the other three kept the caption’s words without it.
A table inside a table is where Pandoc did better. It kept both tables, the inner one inside its cell, written as HTML, the code web pages use for tables, which a Markdown viewer that accepts HTML shows as a table inside a table. LensUp folded the inner table into its cell as lines of text — readable, but no longer a table. markitdown spilled the inner table’s raw table syntax into the cell, and mammoth wrote every cell as a paragraph of its own.
All four accepted the tracked changes (the inserted word kept, the deleted one gone) and dropped the comment.
Two settings change this, and they are not in the table: Pandoc keeps the comment with its --track-changes=all option, and markitdown keeps the picture in place, inside the Markdown, with --keep-data-uris. We ran both on the same files; their output is in the download below.
The fix we made first
In our first run, on 12 October 2026, LensUp moved each Word image to an «Embedded images» list at the end of the Markdown and left only the image’s description where it was. We changed that before publishing: images now stay where they were, and only an image that cannot be placed in the text is listed at the end. The first run’s results are in the CSV below, and its output in the download.
EPUB to Markdown
| What the file has | LensUp | Pandoc | markitdown |
|---|---|---|---|
| Chapter order | reading order | reading order | reading order |
| An illustration with its caption | kept (file), caption kept | kept (file), caption kept | reference only, no file, caption kept |
| A footnote | number linked to the note | Markdown footnote ([^1]) | number with a link that goes nowhere |
| The table of contents | not repeated | not repeated | not repeated |
| The same ornament on every chapter | kept, 3× | kept, 3× | named 3×, no file |
All three put the chapters in reading order, and none repeated the table of contents as text.
LensUp and Pandoc kept the illustration and the ornament at the top of each chapter as image files. markitdown named the illustration once and the ornament three times but exported neither image.
Pandoc wrote the footnote as a Markdown footnote. LensUp wrote its number as a link to the note’s text. markitdown wrote the number too, but its link points to a place that is not in its Markdown.
Which one to use
For a table inside a table, EPUB footnotes as Markdown footnotes, or a picture’s size, Pandoc did better here, if a terminal does not bother you. On the other features we scored, LensUp’s result matched Pandoc’s; it needs nothing installed and was the only one to keep a caption’s number. It folds a table inside a table into text, writes an EPUB footnote as a linked number and drops a picture’s size, and, unlike Pandoc, it does not keep an EPUB caption’s place as a caption, which this test did not score. markitdown and mammoth lost the equations in this test.
Check it yourself
- All results (CSV): one row per feature and tool — what it kept, its version or build, where and when it ran — and LensUp’s first run before the fix.
- Every tool’s output (ZIP): the Markdown and images each tool wrote, which the results are scored from, with LensUp’s first run and the two settings above.
- The samples: lists, footnotes, links, equations, image, caption, table inside a table, tracked changes, comment (Word), and the EPUB book.
Limits
- One small file per feature. Real documents mix them, and a converter can trip on combinations these files do not have.
- Not tested: headers and footers, text boxes, embedded files, right-to-left text, very large files, and any setting other than the ones described above.
- One run per tool. LensUp ran in Chromium on lensup.ai; the other three on a Mac.
- Calibre was not run. mammoth ran through its Markdown output, which its documentation no longer recommends; its main output is HTML.
- We built LensUp and chose the features. The files are above for anyone who wants to rerun them.