Separate pictures.
Or one Markdown file?

Use separate assets for everyday editing.

For a document you keep revising, an assets folder is a practical default. The Markdown stays easy to read, pictures remain ordinary files, and you can replace or reuse an image without putting its encoded contents into the text.

Base64 is useful when you specifically need a single Markdown file with its images inside. Check that the recipient’s app can render data-URI images, and consider the size of the pictures before embedding a whole collection.

The same picture, with different file sizes.

This example uses the site’s small 32 × 32 PNG icon. Both Markdown files contain the same heading, sentence, alt text, and image; only the image destination changes.

![Zizeg icon](sample-icon.png)

![Zizeg icon](data:image/png;base64,iVBORw0KGgo…)

Base64 encodes every three image bytes as four text characters, with padding when needed. Here, 3,258 PNG bytes become 4,344 Base64 characters, plus the Markdown and data-URI prefix. It packages the picture; it does not compress it.

Try the actual files: separate.md with sample-icon.png saved beside it, or embedded.md on its own. These are small generated examples, not a performance benchmark for large documents.

One file is convenient, but the contents still matter.

With separate images, a move can break relative paths if you leave the asset folder behind. Keep the folder structure together. The missing-image guide explains how to repair an existing mismatch.

With Base64, a large screenshot becomes a long string inside the Markdown. A source diff may show a large change when the picture is replaced, and the document carries that data every time it is opened or processed. Many large pictures can make a Markdown file less comfortable to work with.

Embedding also does not guarantee compatibility with every Markdown renderer or publishing platform. Try a small sample in the destination app before converting important documents.

If the recipient only needs to read, standalone HTML offers a single browser-readable file with embedded images, while PDF gives them a fixed-page copy. You can keep separate assets in your editable original.

Try the other storage format without changing your original.

1. Open the existing document.If Zizeg is your default Markdown app, double-click the .md in Finder. Check that the pictures are available before converting.
2. Choose File → Save As… (⇧⌘S).Give the copy a distinct name or destination so it is easy to compare with the original.
3. Choose Assets Folder or Base64 Data URI.Zizeg prepares the new copy, copies or converts accessible image data, and adjusts the new document’s references. The original remains unchanged.
4. Check the copy in Preview and Source.Confirm that images display and inspect the reference. Try the copy in the recipient’s app if you are sharing editable Markdown.

Use Preview (⌘1) or Split (⌘3) to inspect the formatted result. With either set as your default, the formatted view is already visible. Click the active Split control again to swap the panes.

The separate-file workflow also appears in making a copy of a standalone Markdown document.

Choose a default, and keep existing files predictable.

Under Preferences → Editor → Image storage, choose how new or mixed documents should store imported images. Documents that already use one consistent image-storage format continue using their inferred format. Changing this preference does not convert every existing document; use Save As for a converted copy.

For the insertion steps, see adding screenshots and images. If the image points to an online URL instead, see troubleshooting remote images.