Adding images to a Markdown PDF (and why they sometimes vanish)

A practical guide · about 5 min read

Images are one of the most common things people get wrong when converting Markdown to PDF. The image looks fine in the editor, then disappears in the PDF — or shows a broken-image icon. Almost always the cause is the same: the path to the image. This guide explains how image references work and how to make them survive the conversion.

The basic syntax

An image in Markdown looks like a link with a leading exclamation mark:

![a description of the image](path-or-url)

The text in square brackets is the alt text — a description used by screen readers and shown if the image fails to load. The part in parentheses is the important bit: where the image actually lives.

The two kinds of image source

1. A web URL

![Logo](https://example.com/logo.png)

This is the most reliable option for a browser-based converter. As long as your computer is online and the URL is public, the image loads and appears in the PDF. If it doesn't, open the URL directly in a new tab — if it doesn't load there either, the problem is the link, not the converter.

2. A local file path

![Diagram](images/diagram.png)
![Photo](./photo.jpg)

This is where things get tricky. A relative path like images/diagram.png means “a folder called images next to this Markdown file.” That works in your editor because the editor knows where your .md file lives. But when you paste the text into a web converter, the browser has no idea where that folder is — it's just some text, with no file next to it. So local relative paths usually won't render in a paste-based tool.

How to make local images work

You have a few good options:

Host the image and use a URL. Upload it somewhere public (a GitHub repo, an image host) and reference the full https:// URL. Simple and dependable.
Embed the image as a data URI. You can paste the image's bytes directly into the Markdown as a base64 data: URL. It's ugly and makes the file large, but the image is then inside the document and can't go missing:
```
![Icon](data:image/png;base64,iVBORw0KGgo...)
```
Use a local tool that keeps files together. A desktop editor (Typora, VS Code) or Pandoc runs from the same folder as your .md file, so relative paths to local images resolve correctly. If your document is image-heavy and the images are local, this is the smoother route.

Controlling image size

Plain Markdown has no syntax for resizing an image — ![alt](x.png) always renders at the image's natural size, which can overflow the page. Two workarounds:

Resize the source file before you reference it. Exporting the image at the width you actually need is the cleanest fix and keeps the PDF small.
Use an HTML <img> tag instead of Markdown syntax, since most converters allow inline HTML:
```
<img src="chart.png" width="400" alt="Sales chart">
```

Keeping an image from splitting across pages

A tall image can land right on a page boundary and get cut in half. If your tool lets you add CSS, wrapping the image so it can't break helps:

<img src="tall.png" style="page-break-inside:avoid" alt="...">

More on page behaviour in our guide to page breaks.

A quick checklist when an image is missing

Is it a local relative path pasted into a web tool? Switch to a URL or a data URI.
Is the URL public and loading? Test it in a new browser tab.
Is it just too big and pushed off the edge? Resize it or set a width.
Is the syntax right — leading !, parentheses around the source, no stray spaces?

Get the source right and images are one of the easier parts of a Markdown PDF. When you're ready, paste your document into the converter and check the preview — what you see there is what you'll get in the PDF.