Unmarked# Syntax
Markdown links and images
Last updated July 2026
A Markdown link is square brackets around the text and parentheses around the URL: [text](url). An image is the same line with a ! in front, where the brackets hold the alt text and the parentheses hold the image path: . That one exclamation mark is the only difference between the two.
Both fit on a single line, with no closing tag.
Writing a link
A link wraps the words you want to be clickable in square brackets, then puts the destination in parentheses right after, with no space between them.
Read the [CommonMark spec](https://commonmark.org) before you argue about syntax.
That renders the words CommonMark spec as clickable text pointing at https://commonmark.org. The rest of the sentence stays plain. Only the bracketed words become the link.
The URL can be a full web address or a path to another file:
See the [install notes](docs/install.md) in this repo.
Here install notes links to a file sitting next to your document. Relative paths like docs/install.md work the same way web URLs do.
If you want a tooltip on hover, add a quoted title inside the parentheses after the URL:
[The studio](https://untitledapps.dev "untitledapps.dev")
The text in quotes shows when someone hovers the link. It's optional, and most links skip it.
Writing an image
An image is a link with a ! in front. The brackets no longer hold clickable text. They hold the alt text, a short description shown if the picture can't load and read aloud by screen readers. The parentheses hold the path to the image file.
That pulls in trail-map.png from an assets folder next to your document and labels it A hand-drawn map of the trail. Write the alt text as if you were describing the picture to someone who can't see it. It's what a reader gets when the image can't load, and what a screen reader speaks aloud.
Images take a path the same way links do, including a web URL:
This points at a picture hosted on the web instead of a local file. Whether it shows depends on the tool. In Unmarked it renders as the alt text, because the app has no network access to fetch it.
Linking an image
Wrap an image in a link and the picture becomes clickable. You nest the whole image syntax inside the link's square brackets:
[](https://example.com/full-size.png)
The image renders, and clicking it follows the outer link. People use this for thumbnails that open a larger version, or a logo that links home.
In Unmarked
Links work the way you'd expect. In Read mode they're clickable, and clicking one opens it. A link to a local file points at the file beside your document.
Images depend on where the file lives.
A local image, linked by a relative path like assets/trail-map.png, renders in Read mode, in Split mode, and in every export: PDF, Word, and HTML. The HTML export embeds the picture inside the single file, so it travels with the document.
A remote image, linked by an https:// URL, shows its alt text instead of the picture (why). Good alt text earns its keep here. To make the picture appear, save the file next to your document and link it with a relative path.
To add an image while writing, use the Image option in the + Insert menu, which fills in the path for you. The keyboard shortcut for a link is ⌘K.
Unmarked is a free, private Markdown reader and editor for Mac. Read the story , or get in touch.