md2document
Guide

Images in Markdown — when the output is a PDF

Markdown image syntax is simple. The catches are: how to embed a local image without a public URL, how to caption it, and how to keep file size reasonable.

Elia Kuratli
By Elia Kuratli
·3 min read
Open the converter

The syntax

![alt text](https://example.com/image.png)

The text in square brackets is the alt text. The URL in parentheses is the image source. For PDF export, that URL needs to resolve from the browser — either an http(s) URL or a data URL.

Drag-and-drop in the editor

  1. Open the converter.
  2. Drag a PNG or JPG into the editor — anywhere. The image is embedded as a data URL and a Markdown reference is inserted at the cursor.
  3. The reference looks like ![filename.png](img:abc123). The renderer expands img:abc123 to the data URL at preview / export time.

That keeps the Markdown source short and readable in the editor, while the PDF still embeds the actual image bytes.

Captions

Image captions are the alt text. The renderer prints the alt text centered under the image in italics, smaller than the body. If you want no caption, leave the alt text empty: ![](url).

Sizing

Images in the PDF are automatically scaled to fit the content width with the aspect ratio preserved. There is no width attribute in standard Markdown image syntax — if you need a smaller image, resize the source file before embedding. PNG screenshots from a Retina display can be 2× larger than they need to be, which inflates the PDF size.

What works in the PDF

  • PNG (preferred for screenshots and diagrams).
  • JPG (preferred for photos).
  • Data URLs from drag-and-drop.
  • Public HTTPS URLs.

What doesn't

  • SVG inline (use PNG export instead).
  • Localhost URLs that aren't reachable from the browser.
  • Images requiring authentication headers.

Related

← All guides