How to Convert Markdown to PDF with Images
Convert Markdown to PDF and keep images intact — inline images, external URLs, relative paths, sizing, and fixes for missing images.
A picture is often the clearest way to explain an architecture, a UI flow, or a chart — which is why images deserve special attention when you export Markdown to PDF. The good news is that Markdown's image syntax is simple and consistent. The bad news is that "works in my editor" and "works in the final PDF" are two different things: relative paths break, hotlinked URLs get blocked, and images render at the wrong size. This guide walks through how Markdown images behave during PDF export and how to make sure every one of them lands in the final document.
How Markdown Images Work in PDF Export
Markdown uses the same syntax for links and images, prefixed with a !:
When the converter renders the Markdown to produce a PDF, it must resolve that path or URL, fetch the bytes, decode the image, and place it on the page. Each of those steps is a potential failure point:
- Resolution. A relative path like
./images/logo.pngis meaningful only relative to a base directory. If the converter does not know the base, the path is unresolved. - Fetching. External URLs require network access. A browser-based converter that runs locally can usually fetch HTTPS URLs, but a serverless pipeline often cannot.
- Decoding. PDF supports a specific set of image formats. Most raster formats (PNG, JPEG, GIF) work; some vector formats (SVG) need pre-rasterization.
- Layout. PDF pages have fixed dimensions, so an oversized image has to be scaled to fit.
A robust converter handles all four steps transparently. The Markdown to PDF tool, for example, runs entirely in your browser: it resolves local paths, fetches external URLs from your session, and embeds the resulting image data directly into the PDF — no uploads, no server round-trip.
Add Inline Images to Markdown for PDF
Inline images sit in the flow of a paragraph. They are perfect for small icons, inline logos, or formula glyphs. The syntax is identical to a block image; what makes it "inline" is the surrounding text and the absence of a blank line around it:
Click the  button to reload the dashboard.
For block-level images — diagrams, screenshots, charts — put a blank line before and after so the renderer treats the image as its own block element:
The diagram below shows the request flow.
A short checklist for predictable inline images:
- Use PNG or JPEG for photographs and screenshots
- Use SVG only if your converter supports it
- Keep inline icons small (under ~32 px tall) so they align with text
- Provide meaningful alt text for accessibility and PDF tagging
- Place block images on their own line with blank lines around them
Reference External Image URLs in Markdown to PDF
When you reference an image hosted somewhere else, the Markdown file stays small and the image stays where the source of truth lives:
This works well, but it introduces dependencies. For reliable PDF output, keep these rules in mind:
External images require network access at render time. If you generate the PDF offline, or in an environment with a strict outbound firewall, those images will be missing from the result.
To minimize breakage:
- Prefer HTTPS URLs. Many converters refuse plain HTTP for security reasons.
- Avoid hotlink-protected hosts. Some CDNs return a placeholder or a 403 when the referrer does not match their allowlist.
- Pin to stable URLs. A URL that returns a "chart of the day" will produce a different PDF every time you export.
- Download for archival. If the PDF is meant to be a permanent record, download the image and reference it locally so the output is reproducible.
For diagrams you control, consider mirroring them in a local assets/ folder and pointing the Markdown there. The trade-off is reproducibility versus file size.
Control Markdown Image Size in PDF Output
Standard Markdown has no syntax for image dimensions, so sizing is controlled in one of three ways:
1. Image Native Dimensions
The simplest approach: export the source image at the size you want it to appear. A 1200 px-wide PNG renders at roughly 4 inches wide in a typical PDF. This is reliable across every converter because no sizing logic is involved.
2. Inline HTML for Width
Most converters accept a minimal HTML image tag with a width, which gives you explicit control:
```md
<img src="./diagrams/architecture.png" alt="Architecture diagram" width="600" />
```
(Shown here inside a fenced block so the MDX renderer does not parse the tag.) In a converter that passes HTML through to the layout engine, this sets the rendered width to 600 pixels and scales height proportionally.
3. CSS in Renderers That Support It
Some converters accept a stylesheet that targets img elements. This is the most flexible option but the least portable — your CSS may be ignored by the next tool you use.
A quick comparison of sizing approaches:
| Method | Portability | Precision | When to use |
|---|---|---|---|
| Native image dimensions | High | Medium | One-off documents, simple needs |
Inline HTML width attribute | Medium | High | Mixing image sizes within one document |
CSS rule on img | Low | High | Custom pipelines with a known renderer |
Whatever method you choose, remember that PDF pages have fixed width. An image wider than the content area is scaled down to fit, which can make text inside screenshots unreadable. When in doubt, design the source image for the target column width.
Fix Missing Images When Converting Markdown to PDF
When an image shows up as a broken placeholder or an empty box, the cause is almost always one of these:
| Symptom | Likely cause | Fix |
|---|---|---|
| Red X or broken-icon placeholder | Relative path not resolved | Set the correct base directory or use an absolute path |
| Empty box where image should be | External URL blocked or offline at render time | Download the image locally and reference it |
| Image renders in preview but not in PDF | SVG not supported by the PDF backend | Export the SVG as PNG and re-link |
| Image too large or cut off | Source wider than the page | Resize the source or set an explicit width |
| PDF is a static format | Replace with a static PNG or a short video link | |
| Image looks blurry | Source resolution too low for the rendered size | Use a higher-resolution source (2x the display width) |
Two practical habits will save you hours:
- Keep a flat
assets/folder next to your Markdown, with every image referenced by a relative path. This makes the document portable across machines and CI pipelines. - Preview before you export. A live preview that resolves every image is a strong signal the PDF will too. If a preview shows a broken image, the PDF will as well — fix the source first.
Conclusion: Reliable Markdown to PDF with Images
Reliable images in a Markdown to PDF workflow come down to four things: use supported formats (PNG, JPEG, GIF, sometimes SVG), keep paths consistent by housing images in a local assets/ folder, prefer HTTPS for external URLs, and control sizing through native dimensions or an explicit width attribute. Avoid animated GIFs for anything that must appear in print, and always preview before you export. The Markdown to PDF converter handles all of this locally in the browser — no uploads, no server round-trip — and the same document can be routed to Word or HTML when you need a different output. For more walkthroughs, browse the blog.