Start with the document you want to illustrate.
Open your .md file in Zizeg. If Zizeg is your default Markdown app, just double-click it in Finder. You can also start a new document for your notes, a report, or a step-by-step walkthrough.
Use Preview (⌘1) to work with the formatted document, or Split (⌘3) to see Source alongside it. If Preview or Split is your default viewing mode, the formatted view opens automatically. Click the active Split control again to swap the panes; click it again to swap back.
With the default Assets Folder storage, save a new untitled document before adding its first picture. This gives Zizeg a location for the companion image folder.
Editing and HTML or PDF export require a one-time unlock or an active subscription.
Add the picture where it belongs.
Place the insertion point in the document, then use the method that fits what you already have. You can insert pictures in either editable Preview or Source.
- Paste a screenshot or copied image.With image data on the clipboard, use Paste (⌘V) to insert it. This is convenient for illustrating a bug report or adding a screen capture to instructions.
- Drag an image file into the editor.Drop one or more image files from Finder into Preview or Source. Zizeg handles the image insertion and its stored reference.
- Choose a picture from disk.Choose Format → Image…, or use the toolbar’s Insert menu, then select the file.
Supported image formats include PNG, JPEG, GIF, WebP, and SVG. After inserting, check the formatted view to make sure you added the intended picture in the right place.
The default keeps the picture beside your Markdown.
With Assets Folder storage, Zizeg puts imported images in a folder named after the document. It inserts the Markdown reference for you, so you don’t have to type the file path yourself.
Example: a note with one screenshot
Project/
├── Notes.md
└── Notes-assets/
└── screenshot.png
An image reference in Notes.md:
The filename here is an example. The reference points from the Markdown document to the image in its companion folder.
The first operation using the sibling assets folder may show a macOS folder picker. Select or approve the folder containing the document so Zizeg can work with the assets beside it. Zizeg remembers that folder permission.
You can instead use Base64 Data URI storage to embed image data inside the Markdown file. That makes the source larger and removes the need for a separate image file. Choose the default under Preferences → Editor → Image storage; an existing document with a consistent storage format continues using its inferred format.
To make a copy with a different storage choice, use File → Save As… (⇧⌘S). Choose Assets Folder or Base64 Data URI in the panel. Zizeg prepares the new copy and adjusts its image references without changing the original.
For a worked size comparison and the Save As conversion steps, see Markdown images: separate files or Base64 embedding?
Describe what the reader needs to notice.
If Prompt for image alt text is enabled, Zizeg asks for a short description before inserting each image. Use that opportunity to describe its purpose, such as “Export settings with A4 selected,” rather than just “Screenshot.”
You can also edit the description in Source: it is the text between ![ and ] in the image reference. Alt text helps readers using assistive technology understand what the picture contributes.
Keep important instructions in ordinary document text too. A screenshot can show where a control is, while a sentence explains what to do with it.
