Markdown images

An exclamation mark, then the alt text in square brackets, then the source in round brackets. That is the whole of it. Unlike a link, the bracketed text is never displayed when the image loads — it is the alt attribute, read by screen readers and shown when the image fails.

The source can be a full URL, a path relative to the current document, or a site-absolute path starting with a slash. An image sits in its own paragraph if you leave blank lines around it, or flows inline with text if you do not — there is no syntax for floating it left or right.

Alt text describes what the image conveys, for someone who cannot see it. "Screenshot" tells them nothing. "The settings panel with two-factor authentication switched on" tells them what they are missing. Keep it to a sentence.

If the image is purely decorative — a divider, a spacer, an icon repeating a word next to it — leave the brackets empty. An empty alt tells assistive software to skip it, which is better than making it announce a filename. Never start with "Image of"; the software already says that. And do not put the caption in the alt text: a visible caption belongs in a paragraph below, where everyone can read it.

A quoted string after the source becomes the title attribute, shown as a tooltip on hover. It is supplementary — invisible on touch devices and not a replacement for alt text.

Images also take the reference form that links do: define the source once with a label, then refer to it by that label. This is worth doing for a badge or logo you repeat, and for keeping a paragraph readable when the URL is long. The definitions can live anywhere in the file, usually at the bottom, and never render.

Wrap the whole image in link brackets. The image expression takes the place of link text, so you get an opening square bracket, then the full image syntax, then the closing bracket and the URL. It reads awkwardly the first time and is correct.

This is how README badges work: the badge image links to the build, and a thumbnail links to the full-size file. Note the nesting order — the exclamation mark stays with the inner brackets. Getting it backwards produces literal text instead.

Standard Markdown has no syntax for width, height, alignment or captions. The image renders at its natural size, constrained by the container's stylesheet. This is deliberate — Markdown describes content, not layout.

There are three practical routes. Resize the file itself before you commit it, which is the only approach that works everywhere and keeps the page light as a bonus. Use raw HTML where the platform allows it: GitHub accepts an <img> tag with a width attribute in a README. Or rely on a flavor-specific extension — Obsidian and some others accept ![alt|400](src), and a few parsers accept =400x after the source. None of these are portable.

This viewer disables raw HTML entirely, so an <img> tag pasted here appears as literal text rather than an image. The example below shows exactly that.

A relative path resolves against the location of the document being rendered, not against where you wrote it. That is why an image that works in your editor breaks on the published site: the file moved one folder deeper, and images/logo.png now points somewhere that does not exist.

Three rules keep this manageable. Keep images in one folder near the document and use short relative paths. Use a leading slash only when you know what the site root is. And remember that a viewer reading a single pasted file — this one included — has no folder to resolve against, so local relative paths cannot load and only full URLs will. Case matters on most servers even though it does not on Windows or macOS.

GitHub serves images from the repository, so a relative path to a committed file is the most reliable form: it survives forks and does not break when someone clones the repo. Avoid pasting a blob URL copied from the address bar — that is the HTML page around the file, not the file, and it will not display. The raw form on raw.githubusercontent.com works but pins you to a branch name.

Two GitHub-specific extras. Dragging a file into an issue or the README editor uploads it and inserts a permanent attachment URL. And GitHub supports a <picture> element with prefers-color-scheme, so a logo can differ between light and dark mode — raw HTML again, so it works there and not in stricter renderers. Badges are ordinary images from a service such as Shields.io, usually wrapped in a link as shown above.

In rough order of frequency:

• The path is wrong. Check it relative to the rendered file, not the source file, and check the letter case.
• A space in the filename. Encode it as %20, or wrap the source in angle brackets.
• The exclamation mark is missing, so you have written a link instead of an image.
• A space between the square and round brackets, which breaks the syntax and leaves literal brackets on the page.
• A GitHub blob URL instead of a raw or relative path.
• The renderer blocks remote images, or the host blocks hotlinking.
• Raw HTML is disabled, as it is here, so an <img> tag will never display.

One quick diagnostic: if the alt text appears where the image should be, the syntax is right and the file is the problem. If the brackets themselves appear, the syntax is. The links guide covers the bracket rules, which are shared.