Markdown: Markdown Image Syntax and Alt Text
A picture is worth a thousand words—in Markdown, inserting an image takes just one line of syntax, but doing it well takes a bit of know-how.
1. What You'll Learn
- Markdown image syntax basics
- The importance of Alt text and how to write it well
- Adding links to images (click to navigate)
- Centralized management with reference images
- Image best practices (size, format, CDN)
2. A Tech Blogger's Real Story
(1) Pain Point: Images That Won't Load
James runs a tech blog and includes several screenshots per article. At first he hosted images on his own server, but links kept breaking—the server migrated a few times and all the old links went dead. Worse, his image filenames were in Chinese, which some browsers couldn't load. Readers complained about "broken images," and the bounce rate spiked to 70%.
(2) Solution: Use an Image CDN and Naming Conventions
James migrated all images to a CDN-based image hosting service (like Cloudinary), switched to English filenames, and wrote descriptive Alt text for every image. He also used reference-style images in Markdown to centrally manage all URLs. After the switch, image load times improved by 3x and the bounce rate dropped to 35%.
3. Image Syntax Basics
(1) Inline Images
Image syntax is very similar to links, with just an extra ! in front:
| Part | Description | Example |
|---|---|---|
![Alt Text] |
Text shown when image fails to load | ![Screenshot] |
(Image URL) |
The image file address | (https://example.com/img/logo.png) |
(2) Adjusting Image Size
Standard Markdown doesn't support setting image dimensions. Use the HTML <img> tag when needed:
<img src="logo.png" width="200" alt="Set width to 200px">
<img> only when you actually need size control.
▶ Example: Inserting a Local Image
![] but should never be omitted entirely.
5. Images as Links
(1) Clickable Images
Wrap an image inside link syntax to make it clickable:
[](fullsize-image.jpg)
[](https://example.com)
Structure breakdown:
[ ← Link starts
 ← Image (clickable area)
] ← Link ends
(https://example.com) ← Navigation target
▶ Example: Practical Uses of Image Links
## Project Badges
[](https://github.com/user/repo/actions)
[](https://www.npmjs.com/package/package-name)
## Product Screenshots
| Feature | Screenshot |
|:-----|:-----|
| Dashboard | [](img/dashboard-full.png) |
| Settings | [](img/settings-full.png) |
6. Reference Images
Like reference links, image URLs can be centrally managed:
In the body:
![Company Logo][logo]
![Product Screenshot][screenshot1]
Defined at the bottom:
[logo]: https://cdn.example.com/logo.png "Company Logo"
[screenshot1]: https://cdn.example.com/screenshots/v2/dashboard.png "New Dashboard Screenshot"
7. Image Best Practices
(1) Choosing File Formats
| Format | Best For | Pros | Cons |
|---|---|---|---|
| PNG | Screenshots, icons, transparent backgrounds | Lossless, high quality | Large file size |
| JPEG | Photos, complex color images | Small file size | Lossy compression |
| SVG | Icons, logos, illustrations | Infinitely scalable, tiny files | Not for photos |
| GIF | Simple animations | Great compatibility | Limited colors, large files |
| WebP | Replace PNG/JPEG | 25-35% smaller | Some older browsers unsupported |
(2) Image Optimization Tips
1. Control size: keep individual images under 500KB, aim for 100-300KB
2. Use a CDN: accelerate global loading
3. English filenames: logo.png ✅ lo#go.png ❌
4. Logical directories: assets/images/ or img/
5. Write Alt text: every image must have descriptive Alt text
./assets/image.png) is safe, but if you reference an external image host, make sure the service is stable and reliable.
▶ Example: Images in a Product Documentation
## UI Showcase
### Login Page
### Dashboard
> **Note:** Click the image to view the full-resolution version
[](img/dashboard-full.png)
8. Complete Example: Image Showcase in a Project README
Awesome App README Structure:
Title line: # Awesome App + badge images
Screenshot table: Mobile | Desktop
Install command: npm install awesome-app
Logo reference: [logo]: https://cdn.example.com/logo.png
Expected result: A visually rich GitHub README with a project banner, badges, a screenshot showcase, and a centrally managed Logo defined at the end of the document.
❓ FAQ
<img src="url" width="400" alt="description">../assets/image.png for images inside the repo. You can also use absolute URLs for external image hosting..svg file directly in Markdown. You can also embed SVG source code in Markdown (supported by some parsers).📖 Summary
- Image syntax
differs from link syntax by just one! - Alt text is critical for accessibility and SEO—describe both what the image shows and what it does
- Image as link:
[](link)makes the image clickable - Reference images centralize URL management for easier maintenance and migration
- Prefer CDN hosting, English filenames, and controlled file sizes
- When you need size control, fall back to the HTML
<img>tag
📝 Exercises
-
Basic: Insert an image in Markdown (any online or local image) with descriptive Alt text. Then disable image loading in your browser to verify that the Alt text displays correctly.
-
Intermediate: Create a small project where the README.md features a "click thumbnail to view full image" setup—the page shows small images, and clicking them opens the full-size version in a new tab.
-
Challenge: Maintain a "Website Screenshot Gallery" using reference-style images with at least 5 screenshots and URLs defined at the bottom of the document. Then try converting those screenshots to WebP format and compare the file size difference.
