GuideBy MarkovoPublished October 18, 2026Updated October 19, 2026

Pandoc DOCX to Markdown: Export with Images

Run Pandoc inside the directory where you will deliver the Markdown, extract its media there, and move the Markdown file and asset folder together:

pandoc input.docx --from=docx --to=gfm-raw_html --wrap=none --extract-media=assets --output=output.md
        

Put input.docx in that directory before running the command. In our image-bearing DOCX test, this produced working relative image links and preserved the embedded PNG's bytes. The links still resolved after the whole output package was moved. The gfm-raw_html writer produced Markdown image syntax without Word's display dimensions. Original image-delivery results.

1. Keep the Markdown and images in one package

The tested output included this reference:

![Scan with words](assets/media/image1.png)
        

The delivery layout was:

delivery/
          output.md
          assets/
            media/
              image1.png
        

Keep the path that Pandoc writes, including the intermediate media directory. The filename shown here belongs to the test fixture; inspect the actual destinations in your own output rather than assuming every document uses image1.png.

--extract-media=assets writes the embedded media and adjusts image references. Merely choosing an output Markdown filename does not extract images. The Pandoc media-extraction documentation describes this option.

Before handing off the document:

1. Open output.md in the intended documentation tool or renderer.
2. Check both ordinary paragraph images and images inside tables.
3. Copy output.md and the entire assets tree into a new directory together.
4. Open the copied document and check again.

The final copy check catches links that work only because an asset happens to remain elsewhere on your computer.

Why a nested output path can break images

This was the failing layout in our test. The nested directory already existed, and Pandoc was run from its parent:

pandoc input.docx --from=docx --to=gfm-raw_html --wrap=none --extract-media=assets --output=nested/output.md
        

Pandoc wrote assets under the working directory but placed the Markdown under nested. The image reference still began assets/media/. Resolving that reference from the Markdown's directory looked for nested/assets/media/, where the image did not exist.

Run the conversion from the delivery directory instead. If you reorganize the files afterward, update the destinations in the Markdown to match. Absolute asset paths may work on one machine, but they do not make a portable repository or documentation bundle.

2. Choose the image markup your destination accepts

Media extraction and image syntax solve different problems. In our fixture, these writers extracted the same PNG bytes but represented the image differently:

If your destination accepts HTML and you want the sample's dimension information retained, the corresponding command is:

pandoc input.docx --from=docx --to=gfm --wrap=none --extract-media=assets --output=output.md
        

If an extracted image exists but disappears in a publishing system, inspect the generated markup and that system's HTML policy. Changing the asset directory will not fix an HTML element that the destination removes.

These are observations from the named writers and fixture, not proof that every Word drawing or renderer works the same way. For broader output-format choices, see the Pandoc Markdown cheat sheet.

3. Diagnose a missing image before changing converters

To inspect the parsed DOCX, run:

pandoc input.docx --from=docx --to=native --output=parsed.txt
        

Look for an Image node corresponding to the missing figure. If it is present, follow its destination through extraction and output packaging. If it is absent, changing an extraction directory cannot restore an image that the reader did not retain.

An ordinary table-cell image survived our test. Pandoc issue 10018 describes a different case involving grouped graphics that were absent from the parsed document. That report does not mean all images inside Word tables fail. We did not rerun its attachment. Exporting a troublesome drawing from Word and reinserting it as an ordinary picture is a candidate workaround to test, not a verified fix for that report.

Two image occurrences do not always mean two files

Our DOCX reused the same PNG in a paragraph and a table cell. Pandoc extracted one shared file and referenced it twice. Both occurrences resolved, and the extracted bytes matched the source. Count working image references as well as unique files before concluding that an image was lost.

4. Do not confuse image preservation with OCR

The test PNG contained visible words. Those words did not become searchable Markdown text through Pandoc or the default MarkItDown conversion. Preserving an image, retaining its alt text, and recognizing its contents are different outcomes.

If your source is a scanned PDF, use a PDF extraction or OCR workflow rather than putting its pages into Word just to extract the pictures again. If an image contains information the reader needs as text, verify that the chosen recognition path actually returns that text.

Default MarkItDown was also not a substitute for portable image extraction in this fixture. It preserved surrounding text but wrote a truncated data URI:

![Scan with words](data:image/png;base64...)
        

That is not a complete embedded image. The preserved DOCX converter source and image-conversion source explain the default path and data-URI truncation. This finding does not cover every customized MarkItDown configuration.

Prefer a browser-based Word conversion?

Markovo's Word to Markdown tool is another option to try with your own document. Review the returned images, references, tables, and drawing objects before adopting the result.

This guide did not test Markovo on the image-bearing DOCX. Its retained Markovo Word sample was a text report with no pictures. Results from that report, or from a separate PDF scan test, cannot establish DOCX image preservation. Markovo is the service we build; the tested recommendation in this article is the local Pandoc workflow above.

What the image test established

The original local experiment ran on October 17, 2026, using Python 3.11.14, Pandoc 3.11, MarkItDown 0.1.8, Mammoth 1.11.0, markdownify 1.2.3, python-docx 1.2.0, and Pillow 12.3.0.

The synthetic DOCX contained the same PNG in an ordinary paragraph and an ordinary table cell. The image-delivery checks counted references, resolved them relative to the Markdown file, compared extracted bytes with the source, and repeated resolution after moving the output tree.

Source: the separate image_delivery section in the original results JSON. Default MarkItDown recorded a truncated data URI rather than a usable file target; filesystem-resolution counts do not apply to that output. No variant recovered the words printed inside the PNG as text.

The results file also contains broader PDF and Office tests. Their text scores are not image-survival measurements, so they are not reproduced here. The retained Markovo text-only DOCX job was completed on October 14, 2026; it was not a run of this new image fixture.

This experiment did not cover grouped Word drawings, external image links, EMF/WMF display, or a live documentation host. Working paths and identical bytes establish local asset delivery, not identical visual layout in every renderer.

Sources

1. Original image-delivery results
2. Pandoc media-extraction documentation
3. Pandoc issue 10018
4. DOCX converter source
5. image-conversion source