Markdown to PDF with images

How images travel from Markdown into a PDF

An image in Markdown is only a reference: ![alt](path). The picture itself lives somewhere else, on a web server or in a folder next to the file. A PDF has to contain the actual pixels. So the first job of any Markdown to PDF converter is to go and get the images, and this is where most of them fall down: remote images time out, local images become a broken-image icon because the tool never had access to the folder, and the ones that do arrive are pasted at screen resolution and print blurry.

Remote images

URLs starting with http:// or https:// are fetched in your browser while the preview renders. Many image hosts block cross-origin requests, so when a direct fetch fails MDtoDOCX retries through a small proxy that only relays image content types, caps files at 5 MB and keeps nothing. The bytes are then embedded straight into the PDF; the finished file has no external references and opens offline. GitHub user-content URLs, Notion and Imgur links and signed S3 URLs all work as long as the link is reachable when you convert.

Local images

Relative paths such as ./figures/plot.png or images/logo.svg cannot be fetched from the web. Drag the Markdown file together with its folder onto the editor, or drop the whole project directory, and MDtoDOCX reads the image files through the browser's file API and matches them to the paths in the document. Paths are resolved relative to the .md file, exactly as an editor would do it, and ../shared/diagram.png style parent references are followed inside the dropped folder. Base64 data URIs embedded in the Markdown are decoded directly.

Scaling to the page and DPI

A 4,000-pixel-wide photo does not belong on a 15.9 cm line. Every image wider than the printable area is scaled down to fit it while keeping its aspect ratio; narrower images stay at their natural size unless you set a width with an HTML <img width="300"> tag, which is honoured. The DPI option decides how many pixels are kept: 300 DPI is print quality and the default, 150 DPI roughly quarters the file size for on-screen reports, and Original keeps every pixel. JPEGs are re-encoded only when downscaled; PNG and SVG stay lossless, and SVG is embedded as vector so logos and plots print sharp.

Images never break across pages

Each image is wrapped in a figure marked page-break-inside: avoid. If it does not fit in the space left on the page, the whole figure moves to the next page and text fills the gap. Images taller than a page are scaled to fit one page. The caption, built from the alt text, is part of the same figure and cannot be orphaned on the following page. A run of several images, such as screenshots in a tutorial, is paginated one figure at a time so the last one is never split.

Alt text becomes a caption

Alt text is the only place Markdown lets you describe an image, so MDtoDOCX uses it as the caption under the figure, in a smaller face, and also writes it into the PDF's tag tree so screen readers announce it. Switch captions off in the options bar if your alt text is only a file name. Pro adds a numbered "Figure 1:" prefix and a list of figures after the title. The same handling applies when you export to Word: see Markdown to Word with images.

Limits

Free converts up to 10 images per document, each up to 5 MB, which covers the large majority of reports. Pro lifts the count limit, allows 50 MB documents and can run large jobs on our server renderer for very heavy files. Details on Pricing.

Frequently asked questions