Images

Written and tested by the MD Converter editorial team

How to Resize and Align Markdown Images for PDF

Learn how to resize Markdown images without distortion, align them left, center, or right, and keep image-heavy PDF layouts stable.

Markdown does not define image size or alignment

Standard Markdown image syntax is intentionally small:

![Screen layout](./images/screen-layout.png)

It identifies an image and supplies alternative text, but it does not define a portable width, left alignment, or centered alignment. Some renderers accept raw HTML or custom extensions, yet those instructions may be ignored when the same document moves to GitHub, a wiki, another editor, or a PDF converter. A reliable approach is to keep the source portable and apply presentation settings at PDF-export time.

Three ways to add an image

A relative path works well when the Markdown and images travel together:

project/
├── document.md
└── images/
    └── architecture.png

![System architecture](./images/architecture.png)

Preserve that folder relationship when moving or sharing the document. An absolute local path often works only on the author's computer.

A public URL can also be used, but the image must remain accessible while the document is rendered and printed. Authentication, expiring URLs, hot-link restrictions, and network failures can prevent it from appearing. A locally controlled or embedded image is safer for archival PDFs.

Set image size with HTML and CSS

If the Markdown renderer permits HTML, use a width attribute while leaving height flexible:

<img src="./images/architecture.png"
     alt="System architecture"
     width="720">

Reusable classes keep a group of figures consistent:

.figure {
  display: block;
  max-width: 100%;
  height: auto;
}

.figure--half { width: 50%; }

max-width: 100% prevents overflow and height: auto preserves the aspect ratio. Scaling a small source upward does not create detail, so replace a blurry source instead of enlarging it far beyond its native resolution.

Align images deliberately

Use block margins for predictable alignment:

.figure--left   { margin-right: auto; }
.figure--center { margin-inline: auto; }
.figure--right  { margin-left: auto; }

Center major architecture diagrams and full-screen captures, align small procedural screenshots with the left text edge, and reserve right alignment for layouts with a clear reason. Use a consistent rule across the document and explain essential information in nearby text rather than only inside the image. To align the text itself rather than images, see How to Center or Right-Align Text in Markdown.

Start a large figure on a new page

Add a class to selected figures and apply print CSS:

@media print {
  .figure--new-page { break-before: page; }
  figure { break-inside: avoid; }
}

Do not apply break-inside: avoid to a figure taller than one page. Reserve a forced page start for wide diagrams, screenshots that become unreadable when reduced, and figures that must stay with the following section. Recheck TOC references and total page count afterward.

Diagnose missing images

If an image is absent from the preview, check the path, filename capitalization, URL access, file extension, and browser support. Relative paths may be resolved from a different folder than expected. See Why images do not appear in Markdown for a complete diagnostic flow.

If the preview shows the image but the PDF does not, wait for remote images to finish loading before saving from the print dialog. Network-dependent images are inherently less reliable, so embed important assets when possible.

Balance image quality and PDF size

JPEG is usually appropriate for photographs. PNG works well for transparent graphics and screenshots with small text. WebP can reduce size when every target environment supports it. Animated GIFs become static in a PDF, so select the frame that communicates the intended information.

A screenshot around twice its final displayed pixel width often preserves text more clearly in print. At the other extreme, dozens of uncompressed phone photos make a PDF unnecessarily large. Crop irrelevant areas and compress images until further reduction creates a visible defect.

If the PDF uses a colored page background, inspect transparent logos, white artwork, and dark lines carefully. Browser print settings for background graphics may also affect the result.

Write useful alternative text

Avoid generic text such as ![image]. Write a short description of the figure's purpose, for example ![Fields on the order-entry screen] or ![Flow from Markdown parsing to PDF output]. Alternative text supports accessibility, makes broken references easier to diagnose, and helps people search the Markdown source.

Pre-export checklist

  • Every image path or URL is valid
  • Meaningful figures have descriptive alternative text
  • Display dimensions preserve the aspect ratio
  • Images with the same role use consistent width and alignment
  • Text inside screenshots is readable at 100 percent
  • Headings, figures, and captions are not split awkwardly
  • Logos and transparent areas remain visible on the page background
  • The PDF size fits the intended sharing method
  • The saved PDF has been reopened and every page inspected

FAQ

Can standard Markdown center an image?

There is no universally portable syntax for it. Raw HTML may work in one renderer and fail in another. Keep reusable Markdown simple and apply alignment through supported HTML and CSS at export time.

Why does an image look blurry after I enlarge it?

CSS can change displayed dimensions but cannot create missing pixels. Use a higher-resolution source, crop unnecessary space, and avoid displaying the image far beyond its native size.

Should I use percentages or pixels for width?

Percentages follow the available content width, while pixels provide a more explicit display width. In either case, add max-width: 100% and verify the actual print result.

Can a selected image start on a new page?

Yes, when the renderer accepts HTML and print CSS. Add a class to the figure and apply break-before: page; then check that the rule has not created an unwanted blank page.

Summary

Markdown image syntax is portable precisely because it does not contain complex layout instructions. Keep the source straightforward, then use max-width, height: auto, margins, and selective print breaks in an export stylesheet. This produces a cleaner PDF while keeping renderer-specific presentation rules separate from the prose.

Resize Markdown images and create a PDF

Related articles