Markdown Images
Adding images to documents makes content more vivid and easier to understand. Markdown provides simple image insertion syntax that supports local images, network images, and other methods. This chapter will detail various uses of Markdown images.
Basic Image Syntax
Examples
Effect:
Image Syntax Explanation
Alt Text (Alternative Text)
Alt text is displayed when images cannot load, important for SEO and accessibility:
❌  - Missing description
✅  - Meaningful description
✅  - Describes image content
Image Title
Displayed when mouse hovers over the image:
Reference Style Images
Syntax
![Alt Text][Image Reference]
[Image Reference]: Image URL "Optional Title"
Examples
Here are two images:
![Logo][logo]
![Icon][icon]
[logo]: https://github.com/github.png
[icon]: https://example.com/icon.png
Effect:
Here are two images:
Advantages of Reference Images
- Centralized management: Unified definition of image URLs
- Easy maintenance: Only need to modify URL in one place
- Reusable: Same image can be used multiple times
- Clear document: Content not interrupted by URLs
Local Images
Relative Paths
Absolute Paths
Network Images
Direct Links
Stable CDN
Image Links
Use Image as Link
[](Link URL)
Examples
[](https://github.com)
[](./large.jpg)
Effect:
More Flexible Control
<img src="image.jpg" alt="Description" width="300" height="200">
Styled Images
<img src="image.jpg" alt="Description" style="border-radius: 10px; box-shadow: 0 2px 5px rgba(0,0,0,0.3);">
Responsive Images
<img src="image.jpg" alt="Description" style="max-width: 100%; height: auto;">
Image Size Control
Markdown Syntax Limitations
Standard Markdown doesn't directly support size adjustment, use HTML:
<!-- Fixed size -->
<img src="image.jpg" width="500" height="300">
<!-- Width adaptive -->
<img src="image.jpg" width="50%">
<!-- Maximum width -->
<img src="image.jpg" style="max-width: 800px; width: 100%;">
GitHub Flavored Markdown
GitHub supports using | separator:
Image Alignment
HTML Method
<!-- Left align -->
<img src="image.jpg" align="left">
<!-- Right align -->
<img src="image.jpg" align="right">
<!-- Center -->
<center>
<img src="image.jpg">
</center>
Use div Container
<div style="text-align: center;">
<img src="image.jpg" alt="Centered image">
<p>Image description</p>
</div>
Image Captions
Basic Caption
*Image 1: This is a sample image*
Numbered Caption
**Figure 1**: System architecture diagram
Side-by-side Image Captions
| Figure 1: Component A | Figure 2: Component B |
|----------------------|----------------------|
|  |  |
Image Optimization Recommendations
2. Compress Images
Use tools to compress image size:
- TinyPNG
- ImageOptim
- Squoosh
3. Use Appropriate Size
✅ 
✅ 
❌ 
4. Provide Alt Text
✅ 
❌ 
Image Storage Best Practices
Directory Structure
project/
├── docs/
│ └── README.md
├── images/
│ ├── screenshots/
│ ├── diagrams/
│ └── icons/
└── assets/
└── logos/
Naming Conventions
<!-- Recommended -->
<!-- Not Recommended -->
Version Control
- Use Git LFS for large files
- Compress images before committing
- Consider using CDN or image hosting
Image Hosting Solutions
1. Local Storage
Pros: Complete control, no external service dependency
Cons: Increases repository size, slow loading
2. Image Hosting Services
Common Hosting:
- Imgur
- Cloudinary
- Qiniu Cloud
- Alibaba Cloud OSS
- GitHub Repository
3. CDN Acceleration
Image Placeholders
Use Placeholder Services
Common Placeholder Services:
- Placehold.co
- Placeholder.com
- Dummyimage.com
Custom Placeholder
Image Loading Optimization
Lazy Loading
<img src="image.jpg" loading="lazy" alt="Description">
Deferred Loading
Display thumbnail by default, load high definition on click:
[](large.jpg)
Special Image Types
SVG Images
GIF Animations
Data URI Images
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="Embedded image">
GitHub
- Supports local and remote images
- Images hosted in repository
- Auto-generated thumbnails
GitLab
- Supports drag and drop image upload
- Can paste images directly
Typora
- Supports drag and drop image insertion
- Can copy and paste images
- Auto-manages relative paths
VS Code
- Needs preview plugin
- Supports relative path links
- Image hover display
Image Security
Prevent Hotlinking
- Use reference images
- Consider adding watermarks
- Use reliable image hosting
Verify Source
<!-- From trusted sources -->
<!-- Unknown sources, use with caution -->
Practical Examples
Article Illustrations
## Product Introduction
Our product has the following features:
As shown above, the interface is simple and easy to use.
Technical Documentation Flowcharts
## Workflow
System execution flow is as follows:
**Figure 1**: System workflow diagram
Tutorial Step Images
### Step 1: Install Software
As shown above, click "Next" to continue installation.
### Step 2: Configure Settings
After completing configuration, click "Save".
Image Gallery
## Portfolio Display
| Work 1 | Work 2 | Work 3 |
|--------|--------|--------|
|  |  |  |
*Figure 1*: Selected works display
Common Questions
Q: Image not displaying?
A: Check the following:
- Is URL correct
- Does file exist
- Are permissions correct
- Is network accessible
Q: How to adjust image size in Markdown?
A: Use HTML tags:
<img src="image.jpg" width="500">
Q: Images loading slowly?
A:
- Compress image size
- Use CDN
- Use lazy loading
- Provide WebP format
Q: How to batch insert images?
A: Use scripts or editor plugins for automation.
Summary
This chapter detailed Markdown image usage:
- Basic syntax:
!alt format
- Reference images: Centralized image URL management
- Local and network images: Multiple image sources
- Size and alignment: HTML control
- Optimization recommendations: Format selection, compression, naming
- Best practices: Reasonable directory structure and naming
Mastering image usage will make your documents more vivid and professional.
Next: Learn how to create Markdown Tables.