Best Practices for Using Images in Markdown

This guide covers images in Markdown and shows how to keep images accessible, portable, and reliable across repositories, docs sites, and exports. The aim is not merely to make a screenshot: it is to create an asset that stays readable, traceable to its Markdown source, and suitable for repeated publishing.

Use PNG when text, code, tables, or thin diagram lines must stay crisp. JPEG can be smaller for photographic backgrounds, but compression may soften small type. PDF is better for multi-page reading, while DOCX is intended for editable office workflows. Match the format to the destination instead of exporting the same file everywhere.

1. Prepare. write useful alt text that explains the information conveyed.
2. Preview. use stable HTTPS URLs or repository paths that the target renderer can resolve.
3. Export. test reference-style images, titles, dimensions, and dark-mode contrast in the final renderer.

Paste this fixture into the renderer. It is intentionally small so you can verify typography and spacing before using real content.

![Dashboard showing weekly signups](https://example.com/dashboard.png "Weekly signup dashboard")

![Architecture diagram][architecture]

[architecture]: https://example.com/architecture.svg "Service architecture"

CommonMark defines portable core Markdown. Tables, task lists, and some autolinks are GFM extensions, so another renderer may behave differently. Mermaid and KaTeX are separate syntaxes handled by supporting renderers, not by CommonMark itself. Always test the final destination.

• Write meaningful alt text for informative images.
• Keep headings and reading order logical.
• Check contrast in both light and dark themes.
• Inspect the image at its actual display size.
• Keep the Markdown source in version control.
• Re-export when content changes; do not patch text inside a bitmap.

Avoid tiny type, overly wide tables, unexplained acronyms, unstable remote images, and screenshots cropped so tightly that the context disappears. Do not claim identical rendering across every Markdown engine; portability ends where extensions and themes begin.

The factual boundaries in this update were checked against these primary sources:

• https://spec.commonmark.org/current/
• https://docs.github.com/en/get-started/writing-on-github
• https://markdowntoimage.com/

Open MarkdownToImage and test the example with the final width and theme. For related workflows, see the first guide and the second guide.