Pricing Dashboard Sign up
Recent
· 12 min read · MDisBetter

How to Benchmark Word to Markdown Converters on Your Own Documents

There are about a dozen real Word-to-Markdown tools on the market: some commercial, some OSS, some free web tools, some library-only. A published ranking, including one written by a vendor like us, cannot tell you how a tool handles your documents. This guide gives you the method instead: eight tools worth putting on a shortlist, a test set of five document types (a resume, a contract, a technical spec, a financial report and a thesis chapter), a scoring grid on heading, table, image and list preservation, what to look for in each document, and what each kind of tool does by construction.

Tools worth a place on your shortlist

Build a test set

Use real documents from your own workload, anonymised if needed, not synthetic ones. Five document types cover most of what breaks in conversion:

  1. Resume: H1, H2, bulleted lists, simple tables, contact info, hyperlinks. The cleanest case, and your baseline.
  2. Contract: numbered headings (1.1, 1.2, 2.1.a), nested lists, footnotes, definitions, signature block, page numbers in headers/footers.
  3. Technical spec: H1-H4, code blocks, complex tables (merged cells, multi-row headers), inline equations, cross-references.
  4. Financial report: embedded charts (as images), wide tables (12+ columns), multi-column layout sections, footnotes per page.
  5. Thesis chapter: citations (Word bibliography), figure captions, equations (mix of inline and display), footnotes, indexed terms.

If you never handle one of these types, swap it for a document you do handle.

Scoring

Score each tool 0-5 on four axes per document, then average across documents:

Maximum: 20/20. Open each .md output side by side with the original Word document while you score. Disclosure: we build MDisBetter, which is one more reason to run this test on your own files rather than trust any vendor's ranking.

Resume: the baseline

Check that heading levels are correct, that the contact info comes out as a clean paragraph block, that the skills table becomes a GFM pipe table, that hyperlinks are intact and that bullet lists nest properly under each job entry. Look closely at any small table at the top of the page holding contact details: check that it survives.

Takeaway: if a tool fails the resume, drop it. If several pass, the harder documents will decide.

Contract: numbering and footnotes

Numbered headings (1.1.a) are where converters diverge. Check whether the numbering hierarchy survives as headings (with the numbers as part of the heading text), whether deeply nested clauses (4.2.a) keep a consistent heading level or fall back to plain bold, and whether they turn into a regular list instead of headings.

Footnotes: the cleanest outcome is GFM footnote syntax ([^1]), which keeps the reference structure. Score lower when footnote text is inlined in parentheses next to the reference, when markers are dropped and only the text is kept, and lowest when footnotes are lost.

The signature block (a small table at the end with date/name/signature columns) should come out as a table, not flattened into text.

Technical spec: complex tables, code and equations

The hardest test for table preservation. Include a table with merged header cells (for example "Authentication" spanning 3 columns and "Authorization" spanning 3 columns) and a multi-row header. GFM doesn't support merged cells, so no tool can reproduce this exactly. Grade on graceful degradation. The outcomes you can expect:

Which one is acceptable depends on where the Markdown goes: data preservation matters for an LLM, visual fidelity for a rendered docs site.

Code blocks: check that they come out as fenced code blocks, and whether language hints (```python) are kept, rather than turned into indented paragraphs.

Inline equations: the best outcome for math-heavy docs is LaTeX-syntax inline math ($x = y$). Plain text is a partial pass; a dropped equation is a fail.

Financial report: images and wide tables

Put several embedded charts (saved as images in the .docx) and a few wide data tables in this document. Check that every image is extracted and placed where it was, then look at its alt text. A converter either carries over the original alt text from the Word doc, which is often empty or generic like "Chart 3", or, in some paid tools, generates descriptive alt text with AI ("Bar chart showing Q1-Q4 revenue by region"). For LLM ingestion or accessibility that matters; for plain reading it rarely does, so weight this axis by your use case.

Multi-column layouts in Word (text in 2 or 3 parallel columns) will flatten to single-column reading order, because Markdown has no concept of columns. Score whether the reading order is right, not whether the columns survive.

Wide tables (12+ columns) can keep their structure and still be hard to read in Markdown source. That is manual cleanup territory whatever the tool.

Thesis chapter: citations, footnotes and captions

Word's bibliography integration is rare and finicky, so this document separates tools quickly. Check whether in-text citations and the bibliography survive as structured data or collapse into plain text.

Footnotes: a long chapter with many notes shows quickly whether every note survives as a GFM footnote, gets inlined, or disappears.

Display equations: score LaTeX block math highest, a rendered image of the equation next, a dropped equation zero.

Figure captions: the convention is an italic paragraph immediately after the figure. Check whether each caption stays attached to its figure.

What each kind of tool does by construction

Scores tell you how a tool handled your documents. The type of tool tells you what it will cost you to use it:

What MDisBetter does not do: scripted batch processing (you can select several files at once in the browser, but there is no API or CLI) or keep embedded image files: it replaces each image with an AI-generated text description of its content, so score that on your image-heavy test document. It is a web tool only; Pandoc runs on your machine, Mammoth.js is a JS library, and Word2MD offers paid API access.

Picking your shortlist by use case

Then run that shortlist through the test set above.

What about other source formats?

Most document workflows mix Word with PDFs and web pages. For those see best free PDF to Markdown converters and PDF to Markdown, and URL to Markdown. Many production pipelines use one tool for both formats because output Markdown composes cleanly downstream.

Keep your results reproducible

Write down the version of each tool and the date you ran it: web tools update frequently, so re-run the test set before a large migration or when a tool ships a major change. Keep the original .docx files and the .md outputs together so the next run is comparable. For a finer, feature-by-feature version of this method, see how to test Word formatting preservation; for an overview of the tools themselves, see best Word to Markdown tools.

The one-hour version

Pick three of your own representative Word docs (one simple, one complex, one with the features you care about most), run them through the 3-4 tools that match your constraints (free vs paid, web vs local), and score the outputs against the same four axes. Within an hour you'll have numbers for your own corpus, which trump any generic ranking.

Frequently asked questions

Why test on both simple and complex documents?
Resumes are simple: heading, list, paragraph, small table. They tell you which tools to drop, rarely which one to pick. Contracts have numbered nested headings (1.2.3.a), footnotes, definitions, and clause cross-references, which is where converters make different choices. The simpler the doc, the less it separates the tools; the more complex, the more the differences show.
Should I just use Pandoc?
If you're comfortable with the command line, include Pandoc in your test: it is open source, runs locally and scripts well. If you want zero install and a web UI, test web tools such as MDisBetter or Word2MD. If you need AI-generated descriptions of charts, test the tools that offer them, MDisBetter, Word2MD and Hyperleap, on the same image-heavy document. Let the scores on your own documents decide, weighted by the features you actually use.
How do I test conversion quality on my own Word documents?
Pick three docs that represent your real workload (one simple, one complex, one with your hardest feature). Convert each through 2-3 candidate tools. Open the resulting .md files side by side with the original Word docs. Score each on: did headings survive? Did tables survive? Did images survive? Did lists nest correctly? An hour of this gives you your-corpus data far more reliable than any generic benchmark.