The syntax
Nearly identical to link syntax, with a leading ! — the part in brackets is alt text, the part in parentheses is the image path or URL. An optional title, shown as a tooltip on hover in most renderers, can follow the URL in quotes: .
Alt text isn't decoration — it's the accessible content
Alt text is what a screen reader announces in place of the image, and what displays if the image fails to load. An image with empty or missing alt text () is invisible to a screen reader user and provides no fallback if the image link breaks — treating it as optional is a real accessibility gap, not a minor stylistic omission (see the Complete Guide to Web Accessibility for the broader context). Good alt text describes what the image conveys, not just restates that "an image is here."
Why responsive sizing usually needs raw HTML
Core Markdown's image syntax has no way to specify width, height, or responsive behavior — it's deliberately minimal, matching Markdown's overall design philosophy of covering common cases simply and leaving anything more specific to raw HTML, which nearly every Markdown renderer passes through untouched:
<img src="image.png" alt="Description" width="600" style="max-width: 100%; height: auto;">
This is a normal, expected pattern — Markdown handles the common case (a plain image reference) and steps aside for anything requiring finer control, rather than growing its own syntax for every possible attribute.
Common mistakes
- Leaving alt text empty "because the image is just decorative." If an image genuinely conveys no meaningful information, an empty alt (
alt="") is the correct, deliberate choice — screen readers skip it cleanly. Leaving it blank by omission, for a meaningful image, is different and worse. - Assuming Markdown image syntax supports sizing attributes. It doesn't — reach for raw HTML when you need width, height, or responsive behavior.
- Forgetting relative vs. absolute path differences. A relative image path resolves against the Markdown file's own location (or the rendering system's configured base path) — moving the file without updating paths is a common cause of broken images after a site restructure.
FAQ
What happens if I leave alt text blank for a Markdown image?
The image becomes effectively invisible to screen reader users and has no fallback text if the image fails to load — leave it blank only deliberately, for genuinely decorative images with no informational content.
Can I control an image's display size directly in Markdown syntax?
No — core Markdown has no width/height attributes; use raw HTML (<img> with style or width/height) for sizing control, which virtually every Markdown renderer passes through unmodified.
Does the optional title in image syntax do anything important?
It typically shows as a hover tooltip in browsers — a minor usability nicety, not a substitute for meaningful alt text.
Read more about Markdown's syntax and how renderers extend it in the Complete Guide to Markdown.