How to embed an image in Markdown on a Mac

A Markdown file that references ./docs/screenshot.png is only complete while that file is beside it. Paste the document into a ticket, send it as an attachment, or move the folder, and the picture is gone. Embedding it makes the document self-contained: one file, screenshots included.

This guide covers producing the reference in B64, and where it will and will not render.

Get the reference

1. Open Encode

   Click Encode in the sidebar or press ⌘1.

2. Load the image

   Drag it in, press ⌘O, or press ⇧⌘V to encode a screenshot you took straight to the clipboard.

3. Choose Markdown

   Pick Markdown from the format menu. You get a complete inline image reference with a correctly typed data URI inside it.

4. Paste it into your document

   Copy (⇧⌘C) and paste it where the picture goes. Replace the placeholder alt text with a real description.

![A description of the picture](data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…)

Settle the compatibility question first

Markdown has no single specification for this, and renderers differ. Some display a data URI image happily; others strip it for security reasons, because an inline payload in user-supplied text is exactly the kind of thing a cautious renderer does not want to execute.

Where it reliably pays off: documents you render yourself, notes and specs kept locally, bug reports pasted between tools, and anything that has to survive being forwarded as a single file.

Keep it small

An embedded image lives on a single very long line. That has two consequences worth planning around.

• The source becomes hard to read. Put embedded images at the bottom of the file using Markdown's reference syntax if your renderer supports it, so the prose stays legible.
• Version control diffs become useless. A changed screenshot is a one-line change of several hundred thousand characters.

Crop screenshots to the part that matters. It is the single biggest lever on the size of the result — see converting a screenshot to Base64.

A good workflow for bug reports

1. Capture only what matters

   ⌃⇧⌘4 for a selection, with ⌃ held so it goes to the clipboard rather than to a file.

2. Paste, encode, copy

   ⇧⌘V in Encode, then ⇧⌘C. With copy after encoding switched on in Settings, the second keystroke is unnecessary.

3. Paste into the report

   The document now carries the evidence. Forward it anywhere.

Going the other way

Paste a Markdown image reference into Decode and the payload is found inside the brackets and decoded. See how to decode Base64 inside a Markdown file.

Troubleshooting

The image does not render

Most likely the renderer strips data URIs. Test with a very small image to rule out a size limit, then accept that this particular renderer will not do it.

My editor wrapped the line and broke it

Soft wrap is fine — it only changes the display. A hard wrap inserts real newlines and breaks the URI. Turn off hard wrapping for that file.

The file became unpleasant to work with

Too many embedded images, or images that are too large. Crop harder, and keep the embedded ones to the screenshots that must travel with the document.