Why Images Do Not Appear in Markdown — Causes and Fixes

Start with the image reference

A Markdown image normally uses ![description](images/screen.png). A missing exclamation mark creates a link instead of an image. Confirm that punctuation is ASCII and that the path contains no accidental quotes.

Relative paths depend on a base location. If only the Markdown file is supplied to an online converter, its neighboring image folder may not be available. Filename case also matters on many web servers: Screen.png and screen.png can be different files. Prefer simple ASCII filenames with hyphens. Broken links often come from the same path mistakes, so see Why Markdown Links Do Not Open — Syntax and Troubleshooting as well.

For an external image, open its URL directly. Login-protected, expiring, private-network, or hotlink-blocked URLs may work for the author but fail for readers or a PDF renderer. Local file: URLs and computer-specific paths cannot be shared reliably.

Try PNG or JPEG when an unusual format fails. Renaming the extension does not convert an image. SVG files may also depend on external fonts, scripts, or linked resources.

If an image appears in HTML but not PDF, wait until it has loaded before printing and reduce very large files. CSS background images can be omitted when print backgrounds are disabled, so important figures should be regular document images.

For portable distribution, choose an exporter that can embed images as data URLs in a single HTML file. Embedded images increase file size, so resize them appropriately and check for sensitive information before sharing.

Diagnose one missing image versus every missing image

If only one image fails, compare it with an image that works in the same document. Check filename case, extension, file size, URL visibility, and whether the response is actually an image. A URL that ends in .png can still return an HTML login page or an access-denied response. Open the address in a private window to test what an unauthenticated reader receives.

If every image fails, investigate the base path first. Loading a Markdown file does not automatically give a browser access to neighboring folders on your computer. Paths such as images/diagram.png, file:///Users/..., and C:\\Users\\... depend on a local environment that the converter or recipient does not share.

Use portable image references

There are three practical choices. A public HTTPS URL keeps the Markdown small but depends on the remote host. A relative path works when the Markdown and image directory travel together with the same structure. An embedded data image creates a larger document but is self-contained. For a PDF intended for long-term storage, embedding is usually the least fragile option.

If the target renderer supports embedded assets, insert the image into the document instead of keeping a machine-specific file path. Otherwise, preserve the image directory beside the Markdown file and test the package from the same location where recipients will open it.

When preview works but the PDF does not

Wait until all images are visibly loaded before opening the print dialog. Large photographs should be resized before embedding; reducing display width alone does not reduce encoded file size. If a remote image is slow or blocked during printing, download it, verify that you are permitted to reuse it, and embed a local copy.

CSS backgrounds are another special case. Browsers can omit background graphics depending on print settings, so a diagram that carries meaning should use a normal Markdown image rather than background-image. Decorative backgrounds may require the print setting for background graphics.

Image troubleshooting checklist

• Confirm the syntax is ![alt text](source).
• Open the source URL directly and in a private window.
• Match uppercase and lowercase characters exactly.
• Prefer simple ASCII filenames without spaces or URL control characters.
• Convert unsupported HEIC or complex SVG files to PNG or JPEG.
• Replace computer-specific local paths.
• Wait for the preview to finish loading before printing.
• Open the saved PDF and inspect every image page.

Work from syntax to source access, then format, then print timing. Changing one variable at a time makes the actual cause visible.

Frequently asked questions

Why does the image work on GitHub but not in the PDF?

GitHub resolves repository-relative paths and may display private assets through your signed-in session. A browser PDF tool does not automatically share that repository context or authentication. Use a public direct URL or embed the image.

Should alt text be empty?

Use concise alt text that explains the image's purpose. It does not repair a broken source, but it improves accessibility and makes the Markdown understandable when the image cannot be loaded.