Markdown Images Not Showing in Word? How to Package Local Images in a ZIP

Your Markdown document looks complete in the editor, but several images disappear after it is converted to Word. The text, headings, and tables are present, while the DOCX contains blank spaces, broken image references, or only the image alt text.

In most cases, the image itself is not damaged. The converter simply cannot find the file at the location written in the Markdown. Local images require two things to match: the path inside the Markdown and the actual folder structure supplied with the document.

Why local Markdown images disappear

A Markdown image usually contains three parts:

![Quarterly revenue chart](images/revenue-chart.png)

• Alt text: Quarterly revenue chart
• Folder: images
• Filename: revenue-chart.png

The alt text does not contain the image. It only describes it. The actual picture must exist at the referenced path when the document is processed.

A missing image is commonly caused by one of the following:

• The image was not included in the uploaded ZIP.
• The Markdown points to the wrong folder.
• The filename in Markdown does not exactly match the real file.
• An absolute path refers to a folder that exists only on the author’s computer.
• The ZIP adds an unexpected extra directory level.
• The Markdown uses backslashes or inconsistent path separators.
• The file was renamed after the Markdown was written.

Use relative paths instead of computer-specific paths

A relative path describes the image location starting from the Markdown file. It does not depend on a Windows drive letter, macOS user directory, or another computer-specific location.

Recommended

![System architecture](images/system-architecture.png)

Avoid

![System architecture](C:\Users\Alex\Desktop\report\images\system-architecture.png)

The absolute Windows path works only on the original computer. A web-based converter cannot access that desktop folder. The same problem occurs with paths such as /Users/alex/Documents/report/image.png.

A simple ZIP structure that works

For most documents, keep one Markdown file near the root of the package and store images in a clearly named subfolder.

project-report.zip
├── project-report.md
└── images
    ├── cover.png
    ├── architecture.png
    ├── test-results.jpg
    └── deployment-flow.svg

The image references in project-report.md should then look like this:

![Project cover](images/cover.png)

![System architecture](images/architecture.png)

![Test results](images/test-results.jpg)

![Deployment flow](images/deployment-flow.svg)

This structure is easy to inspect, easy to move between computers, and less likely to produce ambiguous paths.

Watch for an extra folder inside the ZIP

A common packaging mistake happens when the author compresses a parent folder rather than its contents.

Before uploading, open the ZIP and confirm that the relationship between the Markdown file and the image directory is exactly the same as it was before compression.

Filename capitalization matters

Some local environments treat uppercase and lowercase filenames as equivalent, while server environments may treat them as different files.

Treat these as different filenames. Use consistent lowercase names whenever possible and avoid renaming images without updating the Markdown.

Use predictable image filenames

Simple filenames reduce path errors and make the package easier to maintain.

Spaces and non-Latin characters can be valid in many systems, but simple lowercase filenames with hyphens are easier to type, compare, share, and troubleshoot.

Do not use a local file URL

The following reference points to the author’s local computer:

![Diagram](file:///C:/Users/Alex/Documents/diagram.png)

Including the same image in the ZIP does not automatically repair that reference. Update the source to a relative path:

![Diagram](images/diagram.png)

What about online images?

A remote image uses an HTTPS address rather than a local path:

![Public diagram](https://example.com/images/diagram.png)

Remote images introduce different risks. The address may expire, block automated access, redirect to a login page, reject external requests, or return HTML instead of an image.

For an important document, storing an authorized copy of the image in the ZIP usually produces a more portable and repeatable package. Make sure you have the right to reuse and distribute the image.

A pre-upload inspection workflow

1. Open the Markdown file in a text editor. Search for every ![ image reference.
2. List the referenced paths. Confirm that each target file exists.
3. Replace absolute paths. Convert them to paths relative to the Markdown file.
4. Check spelling and capitalization. Compare the path character by character.
5. Create the ZIP. Keep the Markdown file and image directories in their expected relationship.
6. Open the ZIP before uploading. Do not assume the compression tool preserved the intended structure.
7. Convert and inspect the DOCX. Confirm every figure at normal reading size.

When the package is ready, upload the ZIP through the

Markdown to Word converter

rather than uploading the Markdown file by itself.

Troubleshooting table

Frequently asked questions

Final checklist