I Tested What a Browser-Based DOCX-to-Markdown Converter Actually Preserves

“Preserves formatting” is one of the least useful promises a document converter can make.

Which formatting?

A Word document can contain semantic heading styles, font sizes, colors, numbered lists, floating objects, page headers, merged table cells, tracked changes, comments, and embedded images. Markdown has no direct representation for many of those things.

So I stopped asking whether DOCX-to-Markdown conversion “works” and tested a narrower question:

Which document structures survive, which become plain text, and which require a deliberate cleanup decision?

I created two controlled .docx files and converted them with MDFold’s browser-based Word to Markdown tool. The first represented a well-structured technical document. The second deliberately used features that are easy to misinterpret or awkward to express in Markdown.

The result was not “everything preserved” or “formatting lost.” It was much more useful:

• real Word heading styles became Markdown headings;
• bold, italic, links, bullets, and numbered lists survived;
• a large bold paragraph stayed bold instead of becoming a heading;
• table text survived, but table structure did not;
• headers and footers were omitted;
• an embedded raster image became a self-contained data URI;
• page layout, fonts, and visual positioning were not reproduced.

That is the behavior this article explains and turns into a repeatable workflow.

DOCX and Markdown describe different things

DOCX can describe both document meaning and page presentation. Markdown mostly describes lightweight document structure.

Microsoft’s explanation of WordprocessingML shows that a Word document is composed of structured elements such as paragraphs and runs, with styles and properties attached to them. A paragraph can be a real Heading 1, or it can be an ordinary paragraph that merely looks like a title because someone made it 22-point bold text.

Those two paragraphs may look almost identical in Word. They are not equivalent to a converter.

The conversion pipeline I tested uses Mammoth to interpret DOCX structure as HTML, then converts that HTML into Markdown. Mammoth’s own documentation is unusually honest about the boundary: DOCX and HTML have a large structural mismatch, and conversion works best when the Word document uses styles for their intended meaning.

That gives us the first rule:

Prepare Word for structural conversion, not visual imitation.

If your real goal is to reproduce page margins, floating text boxes, fonts, headers, or exact pagination, Markdown is the wrong destination. Use PDF for a fixed result or keep the document in DOCX for collaborative editing.

The controlled test documents

I used generated files rather than a convenient hand-picked customer document. This made every expected result explicit and kept personal information out of the screenshots.

Test A: semantic structure

The representative file contained:

• a real Word Heading 1;
• a real Heading 2;
• one sentence containing bold and italic runs;
• an external hyperlink with descriptive text;
• two bullet items;
• two numbered steps;
• a distinctive final checkpoint sentence.

The expected Markdown was:

# DOCX Conversion Field Test

## Release checklist

The **owner** reviews the _generated Markdown_ before publishing.

[Open the release runbook](https://example.com/runbook)

- Verify the title
- Verify the final paragraph

1. Convert the DOCX
2. Review the Markdown

FINAL CHECKPOINT: names, numbers, and links still match.

Test B: features that need judgment

The difficult file contained:

• a visually large, bold title that was still a normal Word paragraph;
• underlined text;
• a two-column table;
• an embedded PNG with alternative text;
• a page header and footer;
• a distinctive final checkpoint sentence.

This second file was designed to prevent a false sense of success. A converter can return non-empty Markdown while still losing the distinction that matters.

The well-structured document converted cleanly

The representative file preserved every checkpoint we asserted: heading levels, emphasis, link destination, both list types, and the final sentence.

The generated Markdown was not character-for-character identical to my hand-written expectation. The converter used extra spaces after list markers:

-   Verify the title
-   Verify the final paragraph

1.  Convert the DOCX
2.  Review the Markdown

That difference is harmless in common Markdown renderers. It is also a useful reminder not to confuse stylistic normalization with information loss.

The important checks were structural:

Word input	Observed Markdown	Result
Heading 1 style	# DOCX Conversion Field Test	Preserved
Heading 2 style	## Release checklist	Preserved
Bold run	**owner**	Preserved
Italic run	_generated Markdown_	Preserved
External hyperlink	Markdown link with the same destination	Preserved
Bullet list	Hyphen list	Preserved
Numbered list	Ordered Markdown list	Preserved
Final checkpoint	Same sentence in the result	Preserved

This is the kind of Word document that converts well: the author used real structure and kept the layout linear.

A title that only looks like a title stays ordinary text

The difficult document began with VISUAL-ONLY TITLE in a large, bold font. It looked like a heading in Word, but it was not assigned a heading style.

The observed Markdown was:

**VISUAL-ONLY TITLE**

This is correct behavior.

Automatically turning every short bold paragraph into a heading would create false structure in labels, warnings, captions, and emphasized sentences. A converter should prefer the document’s semantic style over a guess based on appearance.

Before conversion, open Word’s Navigation pane. If an intended section title does not appear in the document outline, apply the correct Heading style. Do not merely increase the font size.

Microsoft’s Open XML paragraph-style documentation supports this distinction: paragraph style is an explicit document property, separate from the runs that carry text and visual formatting.

Table text survived, but the table did not

This was the most important limitation in the test.

The DOCX table contained:

Owner	Status
Platform	Ready

The observed output was:

Owner

Status

Platform

Ready

The words survived. The row-and-column relationship did not.

The difficult file produced valid Markdown text, but valid is not the same as structurally complete. The table must be rebuilt and checked against the source.

This matters because a flattened table can silently change meaning. Four values in the correct order may still be unusable when the reader cannot tell which header belongs to which value.

For a small table, rebuild it manually and compare every cell with Word. For a large table, use a converter that explicitly supports GitHub Flavored Markdown tables, export the data separately as CSV, or use MDFold’s Markdown table generator after verifying the source values.

Do not trust the presence of all words as proof that the table survived.

Embedded images can survive in an inconvenient form

The test PNG became Markdown with a data: URL:

![A generated status marker](data:image/png;base64,...)

That makes the image self-contained: no separate file is required. It can also make the Markdown enormous, create unreadable diffs, and fail in publishing systems that block data URLs.

For a repository or documentation site, my preferred workflow is:

1. extract the image into an assets directory;
2. give it a stable, descriptive filename;
3. replace the data URI with a relative path;
4. preserve or improve the alt text;
5. preview the page in the actual publishing system.

For example:

![Green deployment status marker](./assets/deployment-status.png)

Mammoth documents inline data URIs as its default image behavior. Other converters may drop images, produce placeholders, or extract separate files. “Images supported” does not tell you which of those contracts a tool provides.

Headers and footers were omitted—and that may be desirable

The difficult DOCX used both:

CONFIDENTIAL DRAFT HEADER
PAGE FOOTER — INTERNAL REVIEW

Neither appeared in the Markdown.

For a web article, this is often desirable. Repeating page furniture is not part of the article’s logical reading flow. For a policy, contract, or controlled document, however, the missing classification, revision, or page note may be important.

The right question is not “did the header survive?” It is “does any information in the header need a new structural home?”

Move essential revision data into front matter, a document metadata block, or the opening section before conversion. Do not rely on page headers to become Markdown automatically.

Underline is ambiguous in Markdown

The underlined sentence returned as plain text.

Markdown has no universal underline syntax, and underlining is often confused with hyperlinks on the web. Mammoth’s default mapping intentionally ignores underline rather than inventing a meaning.

Decide what the underline meant in the source:

• emphasis → use *italic* or **bold**;
• a section label → use a real heading;
• an insertion → write explicit editorial text;
• a link → create a real hyperlink;
• decoration → remove it.

Conversion cannot make that editorial decision safely.

Convert DOCX to Markdown in a reviewable workflow

Here is the process I would use for a real document.

1. Prepare the Word file

• Save legacy .doc files as .docx first.
• Apply Heading styles to actual section headings.
• Accept or reject tracked changes.
• Resolve comments that should not become published content.
• Move essential header or footer information into the document body.
• Simplify merged tables where possible.
• Add useful alternative text to meaningful images.

2. Convert the DOCX

Open MDFold Word to Markdown, choose the .docx file, and wait for editable Markdown to appear. In the version tested on August 2, 2026, the conversion ran in the browser and did not require a document upload endpoint.

3. Check high-risk structures first

Do not begin by proofreading ordinary paragraphs. Check the features most likely to change meaning:

• H1, H2, and H3 hierarchy;
• first and final paragraphs;
• ordered-list numbering;
• link destinations;
• every table;
• image references and alt text;
• footnotes, comments, headers, and footers;
• names, dates, percentages, and negative numbers.

4. Repair the Markdown for its destination

Different destinations support different Markdown extensions. GitHub Flavored Markdown supports pipe tables, while strict CommonMark does not define the same table extension. A data URI or HTML fragment may work in one renderer and fail in another.

Preview the result where it will actually live: GitHub, a documentation generator, a CMS, an Obsidian vault, or another target system.

5. Download and verify the final .md file

Open the downloaded file rather than assuming the editor state and saved artifact are identical. Search for the final checkpoint, inspect the Markdown source, and render it once in the target environment.

The phone-sized workflow worked, but desktop is better for review

I repeated the representative conversion at a 390 × 844 viewport. The file opened, the expected final checkpoint was present, the result remained editable, and the page had no document-level horizontal overflow.

Phone conversion worked in the test. A larger screen is still the better place to compare tables, long links, and image data.

Mobile support is useful for an urgent check. It does not remove the need for a careful desktop review when the source contains complex structure.

When to use a different conversion path

Use this browser workflow for ordinary .docx documents that are mostly headings, paragraphs, emphasis, lists, and links.

Consider Pandoc or another document pipeline when you need:

• batch conversion;
• repeatable command-line builds;
• separate media extraction;
• custom style mapping;
• footnotes, citations, or richer table handling;
• a conversion process that can be reviewed and versioned as code.

Keep Word or export to PDF when the requirement is visual fidelity rather than portable structure.

Privacy is part of the conversion choice

For the tested MDFold workflow, the DOCX was read by browser-side code and the Markdown appeared locally in the editor. That is narrower than claiming that every website conversion is private.

If you use another converter, determine whether the file is uploaded, retained, used for model processing, or logged. This matters for contracts, unpublished research, internal runbooks, customer data, and regulated material.

Local conversion still depends on the device and browser you trust. Extensions, shared computers, managed devices, backups, and downloaded files remain part of the security boundary.

A practical definition of “preserved”

After this test, I would not describe DOCX-to-Markdown quality with one percentage or one checkbox.

I would ask five questions:

1. Is every important sentence present?
2. Is the heading hierarchy still correct?
3. Are relationships—lists, links, tables, notes—still explicit?
4. Are images usable in the target system?
5. Did any page-level information need to be moved into document structure?

A converter can automate syntax. It cannot decide what a visual convention meant to the author.

That is why DOCX-to-Markdown conversion should be treated as a small content migration, not a file-extension swap.

DOCX-to-Markdown FAQ

Can I convert an old .doc file directly?

Not with the MDFold workflow tested here. Save the legacy file as .docx in Word, LibreOffice, or another compatible editor, then convert the new copy. Keep the original until you have checked the Markdown.

Why did my Word heading become ordinary text?

The paragraph probably looked like a heading without using a Word Heading style. Apply the correct semantic style and convert again; do not rely on font size or bold text alone.

Should I keep embedded images as base64 data?

Only when the destination supports data URLs and a self-contained file matters more than readable source. For repositories and documentation sites, extracted image files with stable relative paths usually produce smaller, reviewable Markdown.

If you have a difficult Word document, try the browser-based converter and share one reproducible feature that did not map cleanly. A merged table, floating text box, tracked-change sequence, or image-heavy page is more useful feedback than “formatting broke.”