. The ! distinguishes images from links; otherwise the syntax is identical.
Basic Image Syntax
!A bar chart showing Q3 revenue
Three parts:
!— tells markdown this is an image, not a link[alt text]— the image description (required for accessibility)(image-url)— the URL or file path to the image
Alt Text: Required for Accessibility
Alt text is not optional decoration. It serves two critical purposes:
1. Screen readers announce the alt text to visually impaired users 2. Fallback content displays when the image fails to load
Write alt text that describes what the image shows, not just "image" or "photo":
Bad: 
Better: 
Best: 
For purely decorative images that convey no information, use empty alt text: . This tells screen readers to skip the image.
Adding a Title Tooltip
Add a quoted title after the URL for a hover tooltip:
The title appears as a tooltip when the user hovers over the image. It's the HTML title attribute.
Clickable Images (Image Links)
To make an image clickable, wrap the image syntax inside link syntax:
This is the standard pattern used for:
- Status badges in README files
- Logo images that link to a homepage
- Thumbnail images that open a larger version
Local vs Remote Image Paths
Remote URLs
!Logo
Works in any markdown renderer. The image is fetched from the web at render time.
Relative Paths
Relative paths work in GitHub repositories, Obsidian vaults, and local markdown files. The path is relative to the location of the markdown file.
Absolute Paths
!Image
Useful in static site generators where you know the public root.
Image Sizing
Standard markdown has no native image sizing syntax. Options by platform:
HTML img Tag (Most Compatible)
Works wherever HTML is permitted — GitHub READMEs, most static site generators, MarkdownTools exports.
Obsidian Pipe Syntax
 — set width to 400px
 — set exact width × heightThis is Obsidian-specific and won't work elsewhere.
GitHub (No Native Sizing)
GitHub markdown does not support image sizing directly. Use the HTML width or height attribute.
Platform-by-Platform Breakdown
GitHub and GitLab
Full image support. Both remote URLs and relative repository paths work. GitHub also supports a special syntax for dark/light mode image switching:
Obsidian
Full image support including relative paths within the vault. Drag and drop images into Obsidian and it automatically generates the image syntax with the correct relative path. Supports the |width sizing hint.
Notion
Notion does not embed images via markdown import — it copies the image syntax as text and shows a broken image. You need to upload images directly in the Notion UI.
Discord
Discord does not render embedded markdown images. Instead, it shows the URL as text (and may auto-embed it as a Discord media preview, but that's separate from markdown rendering).
Slack
Slack does not render markdown images. Use Slack's native file upload for images.
Common Mistakes
Missing the Exclamation Mark
[Alt text](image.jpg) — wrong: this renders as a text link, not an image
 — correct: the ! is essential
Empty Alt Text (Accidentally)
 — intentional for decorative images, but accidentally omitting alt text hurts accessibility
 — always add meaningful alt text for informational images
Broken Relative Paths
If your image doesn't load, the most common cause is a wrong relative path. Make sure the path is relative to the markdown file, not the project root.
Spaces in File Names
 — wrong: space in filename breaks the syntax
 — correct: use hyphens instead of spaces in filenames
 — also correct: percent-encode the space
Real-World Use Cases
GitHub README Badges
README files on GitHub almost always include clickable badge images showing build status, code coverage, and license. These use the image-inside-link pattern:
Technical Documentation with Screenshots
For step-by-step guides, screenshots with descriptive alt text help users follow along. Always number or title your screenshots: "Step 2: Click the Export button" as alt text is far more useful than "screenshot".
AI-Generated Reports
When AI tools generate markdown reports, they often include placeholder image paths like . Before exporting to PDF with MarkdownTools, either replace these with real image URLs or remove the broken image references — broken image syntax renders as text in the output.
Full reference: Markdown Images.
Ready to put this into practice? Paste your markdown into the free MarkdownTools PDF exporter or HTML converter — no signup required.