--- title: "Adding images to Markdown on a Mac" author: Pedro Thomaz source: https://coffeetext.app/blog/images-in-markdown-mac --- # Adding images to Markdown on a Mac > Checked November 2026 against the [CommonMark spec](https://spec.commonmark.org/0.31.2/), [GitHub's docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), [Apple's screenshot guide](https://support.apple.com/en-us/102646) and the [VS Code docs](https://code.visualstudio.com/docs/languages/markdown). Coffee isn't affiliated with any of them. An image in Markdown is one line: `![description](photo.png)`. The picture itself stays a separate file, and the part in brackets says where it is. So nearly every problem with Markdown images is a problem with that path, and the fix is usually to keep your images in a folder beside your notes and use relative paths. ## The syntax ``` ![A cup of coffee on a desk](images/cup.png) ![A cup of coffee on a desk](images/cup.png "Monday morning") ![Logo](https://example.com/logo.png) ``` The text in square brackets is the description, which [CommonMark](https://spec.commonmark.org/0.31.2/) says is standardly used as the image's alt attribute. Screen readers read it out, so write what the picture shows. The quoted part in the second example is an optional title. ## How relative paths work A relative path starts from the folder holding the note, not from wherever your app or Terminal happens to be. | Where the image is | Write | |---|---| | Same folder as the note | `![](cup.png)` | | A folder inside the note's folder | `![](images/cup.png)` | | A folder beside the note's folder | `![](../images/cup.png)` | | Somewhere else on this Mac | `![](https://coffeetext.app/Users/you/Pictures/cup.png)` | | On the web | `![](https://example.com/cup.png)` | Prefer the first three. A path starting `/Users/you` works only on your Mac and breaks as soon as the note goes anywhere else. [GitHub's docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) recommend relative links for repositories too, so that they keep working in clones. ## Spaces in file names Under CommonMark, a plain image address can't contain a space. Either write the address in angle brackets or replace each space with `%20`: ``` ![]() ![](my%20photos/cup%20one.png) ``` Simplest of all is not having spaces in image names in the first place. `cup-one.png` needs neither. ## Where to keep images Markdown has no rule about this, so it's a choice. These three are common: - **One folder per project.** An `images` or `attachments` folder beside the notes. Easy to back up and easy to move as a whole. - **Beside each note.** Simple while notes are few, and untidy once a folder holds forty notes and a hundred screenshots. - **On the web.** Nothing to move, but the image disappears if the host removes it, and it can't be seen offline. Whichever you choose, move the images and notes together. Moving a note on its own in Finder breaks its relative paths, as nothing updates them for you. ## Getting a picture in, on a Mac Screenshots are the most common source. [Apple's guide](https://support.apple.com/en-us/102646) covers the shortcuts: ⇧⌘4 for part of the screen and ⇧⌘5 for the Screenshot app. Add Control, as in ⌃⇧⌘4, and the picture goes to the clipboard rather than to your desktop. Plain text editors can't do much with an image on the clipboard, so you save the file and type the path. Some editors help. The [VS Code docs](https://code.visualstudio.com/docs/languages/markdown) describe dragging a file into a Markdown editor and pasting image data, for example. ## Setting the size Standard Markdown has no syntax for size. Where raw HTML is allowed, you can use `A cup`. It's fine on many sites, but it isn't Markdown, and not every app shows it. If you need one fixed size everywhere, resize the file before you add it. ## What Coffee does Paste an image, drag one into the note, or type `/` at the start of a line and choose Image. Coffee copies the picture into an `attachments` folder beside the note, creating it if needed, and adds a line such as `![](attachments/clip-1a2b3c.png)`. The short ending keeps two images from claiming the same name, and spaces are encoded for you. A pasted image is saved as PNG, and a dragged one keeps its format. The description is left empty, so add one if the note will be read by anyone else. Images show at their own size, and scale down to fit the column. There's no way to set a size in Coffee. Coffee also reads relative paths you write yourself, full paths, and paths starting `~/`. Exports look relative to the note, so stick to relative paths for anything you'll export. A few limits are worth knowing: - **An image has to be alone on its line to be drawn.** One in the middle of a sentence stays as text in the note, and a PDF prints only its description, although an HTML export does include the image. - **A title doesn't show in the note.** Coffee understands one in double or single quotes, so `cup.png "Monday"` still finds `cup.png`. An HTML export keeps it as the image's title, and a PDF doesn't print it. - **HTML `` tags aren't drawn.** They show as text. - **A missing image shows its source**, so you can see what it was looking for. Check Document, in the Note menu, lists every image it can't find in a note. If you move a note to another folder from inside Coffee, its images are copied along. Copied rather than moved, because another note may use them, and nothing already in the new folder is replaced. An image on a `../` path isn't copied, so check those. Renaming a note doesn't touch image links. Moving a note in Finder gets none of this, so its relative image paths will need fixing. In a [private note](https://coffeetext.app/blog/password-protect-notes-mac), an image you add is encrypted before it's written to disk, under a name that doesn't reveal the original. ## Web images in Coffee Images from the web appear in your own notes, with their sites able to see your IP address, as with any web image. You can turn them off in Settings, under "Images from the web". They're never loaded in private notes, or in a note opened from outside your library. Coffee is strict about them, as a note can come from anywhere. An image has to be HTTPS on the standard port from a public host name, with no IP addresses or local names, under 15 MB, and a PNG, JPEG, GIF or WebP. SVG is refused on purpose. A sandboxed helper with no access to files or the network decodes each download, and Coffee keeps only a PNG it writes itself from the result. ## Images in exports An HTML export puts local PNG, JPEG, GIF and WebP images inside the file, so it stands alone. A web image stays a link to the web, so it can change or disappear. A PDF includes local images and leaves out web ones, so if a picture must appear in the [PDF](https://coffeetext.app/blog/markdown-to-pdf-mac), download it first. Quick Look shows a placeholder for images, as its sandbox can't read them. ## Questions ### Why doesn't my Markdown image show? Usually the path. It's relative to the note's folder, it's case-sensitive on some systems, and a space in it needs `%20` or angle brackets. Check that too if the note has moved since you added the image. ### Can I embed an image inside a Markdown file? Not as Markdown normally works. The file holds a link and the picture stays separate. Some tools accept a `data:` address containing the whole image, but it makes the file enormous and hard to edit. ### Does Coffee change my image files? A pasted image becomes a new PNG in `attachments`, and a dragged one is copied there, leaving your original where it was. Images you link to by path aren't copied or changed. ### Can I resize an image in Markdown? Not in standard Markdown. Use an HTML `` tag where your publishing tool allows it, or resize the file itself. --- Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt