mdtopdf.

Document field notes

Images in a Markdown PDF: size, resolution and alt text

How image width changes printed resolution, why a broken path prints alt text, and how to check figures and screenshots in the exported PDF.

Published 2026-10-24 · Markdown to PDF editorial

An image that looks sharp in a preview can print soft, and a diagram that looks small on screen can consume most of a page. The preview shows layout; the PDF decides how many pixels land on each printed inch. Check both before sending a document with screenshots or figures.

What the converter supports

Markdown to PDF lists images among its supported content, and its public product notes describe image and video links and browser-side rendering. Images are laid out with the document, so their printed size is affected by the page size and by any width you set. The observations below come from one A4 export; a US Letter page will shift the available width slightly.

A fixture with four image cases

# Images

Default Markdown image:

![Transparency demo](https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png)

HTML width 120:

<img src="https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" width="120" alt="Small demo">

Broken relative image:

![Missing diagram](docs/missing.png)

Linked image:

[![Linked demo](https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png)](https://example.com)

What the checks showed

The fixture was opened in the live preview and exported as an A4 PDF on 24 October 2026. Image dimensions and effective resolution were read from the exported file, not estimated from the screen.

  • The default image filled the text column. The 800 × 600 source image was embedded at about 119 ppi and occupied most of the page width. That is adequate for screen reading and marginal for a printed photograph.
  • A width of 120 kept the detail in a smaller space. The same source image, set with width="120", printed small and was embedded at about 640 ppi. It kept its full pixel dimensions and simply occupied fewer printed inches.
  • A broken relative image printed a placeholder. The missing docs/missing.png produced a broken-image icon and the alt text "Missing diagram" in the PDF.
  • The linked image stayed clickable. Wrapping the image in a Markdown link produced a PDF link annotation to the destination.
  • The full-width image changed the page flow. The file ran to two pages: the default image and the small examples filled page 1, and the linked image moved to page 2. A full-width figure can push following content further than expected.
  • The transparent PNG printed on white. The source's transparent background was rendered against the page, so dark artwork remained readable. Do not assume a transparent logo will look right on a coloured or textured background in print.

Size images for the printed page

  1. Estimate the effective resolution. Divide the image's pixel width by the printed width in inches. An 800-pixel image at 6.7 inches is about 119 ppi; the same image at 1.25 inches is about 640 ppi. The second has more detail per inch, not more pixels.
  2. Aim for the output, not the screen. Text in screenshots needs more resolution than a decorative photo. If a screenshot's labels are hard to read at 100% in the PDF, crop the screenshot to the relevant area or give it more width rather than enlarging the whole page.
  3. Use a width for diagrams and icons. An explicit width prevents a small diagram from being blown up to the full column. HTML <img width="…"> survived the export in the check; Markdown's own image syntax does not carry a width.
  4. Do not enlarge beyond the source. Setting a width larger than the image's natural size does not add detail. A small logo stretched across the page will look soft no matter what the PDF reports.
  5. Keep important screenshots near native size. If the reader must read interface text, a full-width screenshot of a whole desktop is usually worse than a crop of the relevant panel at a readable scale.
  6. Plan for the page break. A full-width figure can leave a large gap or push the next section to a new page. Put figures where a break is acceptable, and check the pages that follow.

Always give an image a fallback

Alt text is not only an accessibility field in this workflow; it is what the PDF shows when the image fails. A broken path produced a visible icon plus the alt text in the check. Write the alt text as a short description of what the image contributes, not as a filename. "Architecture: request path from browser to renderer" is useful; "diagram" is not.

Use an absolute image URL. A relative path is resolved by the converter's own page, not by your repository, so docs/missing.png becomes a request to the converter's domain. Repository-relative paths need rewriting before export.

Check the images in the PDF

  1. Read every label in every screenshot at 100%. If you need to zoom, the printed page will be worse.
  2. Check the widest and tallest figure. Confirm it fits the page width and has not created an awkward gap or an orphaned caption.
  3. Look for broken-image icons and alt text. Any placeholder means the path failed. Fix the source and export again.
  4. Click a linked image and a linked caption. Confirm the destination survived. In the check, an image wrapped in a Markdown link remained clickable.
  5. Print one page in greyscale. Confirm the image still carries its meaning without colour, especially charts that use colour-coded series.
  6. Check the file size. Large images inflate the PDF. If the recipient has an attachment limit, reduce dimensions before export rather than compressing the finished file blindly.

Diagnose an image that printed badly

A broken-image icon appears
The path failed. Use an absolute, reachable URL and confirm it loads in a private browser window before exporting. The alt text is printed beside the icon.
The image is blurry
It was enlarged beyond its natural pixel size. Use a larger source, crop to the important area, or reduce the printed width.
The image is enormous
It filled the column by default. Set a width in HTML or crop the source. A full-width figure should be a deliberate choice.
The figure pushed content to a new page
Move it earlier or later in the source, reduce its height, or split the surrounding text. Page flow is part of the layout, not an export bug.
The linked image is not clickable
Check the Markdown link syntax around the image. In the test, a correctly wrapped image produced a link annotation; a bare image does not.
A transparent logo looks wrong
It is composited against white in the PDF. Add a solid background in the source if the artwork needs one, and check it in greyscale.

Delivery checklist

  • Every image has a deliberate printed width.
  • Screenshot text is readable at 100% in the PDF.
  • No image is enlarged beyond its source pixels.
  • All paths are absolute and load before export.
  • Alt text describes the image's contribution, not its filename.
  • Linked images and captions were clicked in the PDF.
  • Page breaks and greyscale were checked around each figure.
  • File size is acceptable for the intended recipient.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. Measurements come from one A4 export inspected with a PDF image lister on that date; effective resolution varies with page size, margins and image dimensions. No print-shop certification or cross-viewer audit is claimed.