Images in Markdown: Syntax, Alt Text, and Sizing
Images in Markdown: Syntax, Alt Text, and Sizing
Adding images in markdown is straightforward once you understand the syntax, but doing it well requires attention to a few details that many writers overlook. This guide covers everything from the basic image tag to alt text best practices, reference-style images, sizing workarounds, and advice on where to host your images.
Quick Answer: To add an image in markdown, use . The exclamation mark tells the parser it is an image. Alt text is required for accessibility and SEO: pages with descriptive alt text rank measurably higher in image search, and over 7 million screen reader users depend on it to understand visual content.
What Is the Basic Image Syntax in Markdown?
The image syntax in markdown looks like a link with an exclamation mark prepended:
A concrete example:
Breaking it down:
!- tells the parser this is an image, not a link[alt text]- the text description of the image (critical, covered in depth below)(image-url)- the path or URL to the image file
You can use relative paths for images in the same project, or absolute URLs for images hosted elsewhere:
How Does the Image Title Attribute Work?
Just like links, images accept an optional title as a tooltip. Add it inside the parentheses after the URL, in double quotes:
The title appears when a user hovers over the image in most browsers. It is different from alt text: the title is supplementary context, while alt text is a functional replacement for the image when it cannot be seen.
Why Does Alt Text Matter More Than Most Writers Realize?
Alt text (alternative text) is the single most important attribute on any image. It serves two distinct purposes that many people conflate.
Accessibility. Screen readers read alt text aloud to users who cannot see the image. Without meaningful alt text, a blind or visually impaired reader receives either silence or a raw filename like IMG_20240315_084322.jpg, which provides no information. The WebAIM Screen Reader Survey found that missing or poor alt text is one of the top 3 most frustrating web accessibility issues reported by screen reader users.
SEO. Search engines cannot see images. They rely entirely on alt text (along with surrounding context and file names) to understand what an image depicts. Images with descriptive alt text can appear in image search results and contribute to the overall topical relevance of a page.
How Do You Write Good Alt Text?
Good alt text is:
- Specific - describe what is actually in the image, not just “image of a thing”
- Concise - aim for under 125 characters; screen readers may truncate longer text
- Contextual - consider why this image is on this page and what it adds to the content
- Not redundant - do not start with “image of” or “photo of,” the reader already knows it is an image
Bad alt text:
Good alt text:
What About Decorative Images?
Some images are purely decorative and carry no informational content (a background texture, a decorative divider). For these, use an empty alt attribute. In markdown, that means empty brackets:
An empty alt tells screen readers to skip the image entirely, which is the correct behavior for decorative content.
What Are Reference-Style Images and When Should You Use Them?
Just as with links, you can use reference-style syntax to keep image declarations separate from the main text. This is especially useful in documents with many images:
The editor interface looks like this:
![edtr.md editor screenshot][editor-screenshot]
And the export panel:
![PDF export dialog][export-dialog]
<!-- Reference definitions at the bottom of the document -->
[editor-screenshot]: /images/editor.png "Main editor interface"
[export-dialog]: /images/export.png "PDF export options"
Reference-style images make the document source considerably cleaner when image URLs are long (CDN paths with version hashes, for example). This pattern is especially common in technical documentation projects with many screenshots. For a full guide on structuring larger markdown documents with consistent image practices, see technical documentation with markdown.
How Do You Control Image Size in Markdown?
Standard markdown has no native syntax for controlling image dimensions. The  syntax renders the image at its natural size, constrained by the container it is in.
HTML Workaround
The most portable way to set image size in markdown is to fall back to HTML:
<img src="/images/screenshot.png" alt="Editor screenshot" width="600" height="400">
Most markdown renderers accept inline HTML. You can use either pixel values or percentages:
<img src="/images/diagram.png" alt="Architecture diagram" width="100%">
Extended Markdown Syntax
Some markdown processors support extended image syntax with size parameters. The format varies by platform:
{width=600}
{ width=50% }
These extensions are not part of the CommonMark standard and will not work in all environments. If portability matters, stick with HTML for sizing.
CSS Classes (for Site Builders)
If you are using a static site generator like Hugo, Jekyll, or Next.js with markdown, you can often append CSS classes to images through your markdown processor configuration. For example, with some processors you can write:
{.responsive-image}
And then style it with CSS:
.responsive-image {
max-width: 100%;
height: auto;
}
Should You Use Hosted or Local Image Paths in Markdown?
Choosing where your images live affects both your workflow and the reliability of your documents.
Local Paths (Relative URLs)
Pros:
- No external dependency; works offline
- Images are part of your project and can be version-controlled
- Fast rendering for locally served content
Cons:
- Moving the document without the images breaks the references
- Not suitable for documents shared as single files
Best for: Documentation sites, repositories, projects where images are part of the codebase.
Hosted Images (Absolute URLs)
Pros:
- Document file is self-contained as a single
.mdfile - Images are accessible from anywhere without file dependencies
- CDN-hosted images load fast globally
Cons:
- Broken link if the hosting service changes or the URL path changes
- Requires internet access to render
Best for: Blog posts, newsletters, documents shared across different contexts.
Choosing a Hosting Strategy
For long-lived content, store images in a location you control (your own CDN, an S3 bucket, your repository’s assets folder) rather than hotlinking from third-party sites. Third-party image URLs can disappear without notice.
For technical documentation committed to a git repository, keeping images in a /docs/images or /assets folder alongside your markdown files is a solid convention. The images are versioned together with the content that uses them. GitHub also lets you upload images directly into issues and pull requests, generating stable CDN URLs you can use in any markdown file. See markdown for GitHub for more on working with images in GitHub contexts.
Which Image File Format Should You Use in Markdown Documents?
The format you use for images affects both quality and performance:
| Format | Best For | Notes |
|---|---|---|
| PNG | Screenshots, diagrams, graphics with transparency | Lossless, larger file sizes |
| JPG/JPEG | Photographs, complex imagery | Lossy compression, smaller files |
| WebP | Everything (where supported) | Better compression than PNG and JPG |
| SVG | Icons, logos, diagrams | Scales perfectly at any size |
| GIF | Short animations only | Very limited color range |
WebP images are typically 25-35% smaller than equivalent PNG or JPG files at the same visual quality, making them the preferred format for web performance. As of 2024, WebP has 96% global browser support according to caniuse.com, so it is now safe to use as a default for any web-published markdown content.
For diagrams and flowcharts that you want to express as text rather than binary image files, consider Mermaid diagrams in markdown. Mermaid lets you define diagrams directly in code blocks, which means they are version-controlled, editable as text, and render perfectly at any resolution.
How Do You Make a Clickable Image in Markdown?
You can make an image clickable by nesting the image syntax inside a link:
[](https://example.com/full-size)
This is the standard pattern for:
- GitHub badges (build status, license, version)
- Thumbnail galleries that link to full-size images
- Product screenshots that link to live demos
For a full guide to link syntax including relative links, anchor links, and reference-style links, see links in markdown.
What Are the Most Common Image Mistakes in Markdown?
Missing alt text. An image with no alt attribute (![]()) is inaccessible and provides no SEO value. Always include meaningful alt text unless the image is purely decorative.
Generic filenames. IMG_001.jpg gives search engines no information. Rename image files descriptively before uploading: markdown-editor-preview.png is far better.
Incorrect path separators. On Windows, paths use backslashes (\), but markdown URLs should always use forward slashes (/). Always use forward slashes in markdown image paths.
Hot-linking without permission. Embedding images from another site without permission can violate their terms of service and will break if they change their URLs.
How Do You Start Adding Images in Your Markdown Documents?
Try the image syntax right now in edtr.md. Paste an image URL from the web using the  format and watch the preview render it instantly. Experiment with different alt text descriptions to see how they affect the rendered output.
For the full reference of markdown syntax including headings, emphasis, lists, and code, keep the markdown cheat sheet handy.
Try it yourself
Open edtr.md and start writing Markdown with live preview, diagrams, math, and PDF export. Free, no sign-up.
Open editor