Markdown images
An image is written like a link with an exclamation mark in front of it. The square brackets hold the alt text, not a caption.
Markdown has no syntax for width or height. GitHub also accepts `` style suffixes for theme switching.
A relative path is resolved by whatever is showing the file
 does not point at a file. It points at a name, and the thing rendering the document decides what that name means: on GitHub, the directory the markdown file sits in; in a static site generator, the built page's URL; in a chat window, nothing at all.
That is why images are the first thing to break when a document moves. A README that renders on GitHub loses every image on npm, in a documentation site that flattened the folder structure, and in any viewer that was handed the file rather than the folder. This site hit it too: the sample README on our own examples page linked to a relative image and produced a link to a page that does not exist, until we made the demonstration documents render a placeholder instead.
The fix, where the document has to travel, is an absolute URL. It costs you the ability to move the images with the file, which is the trade nobody enjoys making.
What usually goes wrong
- A relative path is resolved against whatever is displaying the file, so an image that works on GitHub can be missing everywhere else.
- The text in brackets is alt text for screen readers and for when the image fails to load. It is not a caption and is usually invisible.
- Relative paths are resolved against wherever the file is rendered, which is why images in a README break when the same file is shown somewhere else.
- Markdown cannot centre or float an image. That is HTML and CSS.
- An empty alt (
) is correct for a purely decorative image and wrong for anything carrying meaning.
Where it behaves differently
It renders as written on GitHub, GitLab and VS Code preview. Everywhere else in this table it does something else, and that is worth reading before you paste.
| Platform | Behaviour |
|---|---|
| Obsidian | Also takes a size: ![[photo.png|300]]. |
| Notion | Not supported. The syntax arrives as its own punctuation. |
| Discord | Not supported. The syntax arrives as its own punctuation. |
| Slack | Not supported. The syntax arrives as its own punctuation. |
For the .md file that arrives in Mail
A markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
For iPhone and iPad.