How to Convert Markdown to PDF with Images
Troubleshoot images missing from Markdown PDF exports: local paths, CORS, image sizing, page breaks, and the limits of image-based PDF output.
To include an image in this site's PDF export, the browser must be able to display it and the capture process must be allowed to read it. An image appearing in preview establishes only the first condition. The PDF converter captures the rendered document into page images, so verify the downloaded file before sharing it.
Start with one image and a caption
# Deployment guide
Figure 1. The client sends a request to the API.
The URL is a placeholder: replace it with an actual image URL you control or have permission to use. Use the image file's address rather than a sharing page or gallery page. Add a visible caption if readers need one; Markdown alt text does not automatically create a caption beneath the image.
Export this small sample before adding a full document. Check the image's content, scale, and page placement in the PDF. This isolates image access problems from the layout and memory demands of a large report.
Why a local image path fails
A .md file is text. Uploading it does not include the assets folder beside it, so a path like ./assets/diagram.png cannot refer to that local file in this web tool. The browser resolves relative addresses against the web page, not against the folder on your computer.
For public images, use a stable HTTPS URL whose host permits cross-origin access. For confidential files that must remain entirely local, use a local converter that can read the document and its attachment folder, or insert the images in a document editor. Publishing private images to make a URL reachable is not a necessary step in document conversion.
Diagnose preview versus export failures
| Observation | Possible cause | What to check next |
|---|---|---|
| Image is absent in preview | Relative path, unavailable URL, login requirement, or a sharing page | Check that the address returns the actual image |
| Image appears in preview but not PDF | The host blocks cross-origin capture | Use an image host you control with appropriate cross-origin permission |
| A different image appears | Dynamic or expired URL | Use a stable source and verify it immediately before export |
| Image is blurred | Low-resolution source or rasterization | Use a clearer source and check the PDF at normal reading size |
| Export stalls on an image-heavy document | Large images or browser memory pressure | Resize assets and try a shorter representative section |
A normal browser image can load without permitting JavaScript to read its pixels. CORS controls that distinction. Repeated downloads, changing the alt description, or adding blank lines will not fix a host permission problem.
Size images for the reading task
A large pixel count does not guarantee readable labels after the image is scaled to portrait paper. Wide architecture diagrams often work better as several focused figures. Crop unnecessary margins from screenshots and use short, legible labels.
This converter captures an A4 portrait layout. Its PDF images are rasterized, so SVG artwork is not retained as vector artwork and an animated GIF does not remain animated. Inspect dense charts and fine lines in the downloaded file, not just in the full-width browser preview.
A manual page break can move a figure to the next page:
Introductory paragraph.
<!-- pagebreak -->
## Architecture
Replace the placeholder URL. The marker starts a new section, but a figure taller than the usable page still needs resizing or restructuring. Do not assume that a blank line creates a new page.
Accessibility and searchable content
Describe images in alt text for the HTML preview and include visible explanatory prose where readers need it. The current direct PDF exporter does not create a tagged PDF or a text layer; image alt text is not transferred into a tagged PDF reading structure. Text inside a screenshot, and ordinary body text, are captured as images.
If readers need text selection, search, screen-reader navigation, or accessible figure descriptions, use a workflow that preserves text and supplies appropriate PDF tags. DOCX export gives you an editable document to review in a document editor before producing that deliverable.
Final image checklist
- Every source URL points to the intended image and is stable enough for this export.
- Each figure is visible in the downloaded PDF.
- Labels remain legible at the intended reading or printing size.
- The caption and its figure stay close together.
- No confidential local path or temporary access token is exposed in a fallback or reference.
- The recipient is comfortable with image-based pages; otherwise use a text-preserving workflow.
The Markdown is processed in the browser without upload to a conversion server. Remote images still contact their hosts during loading, so this is not a network-free workflow.