图片语法

Mizuki 主题对图片功能进行了增强，支持画廊浏览、懒加载、自动优化等特性。

基础语法

Markdown 图片语法：

![替代文字](图片路径)
![替代文字](图片路径 "图片标题")

图片路径

Mizuki 主题支持三种图片路径格式：

1. 远程图片

使用完整的 URL 地址：

![示例图片](https://example.com/image.jpg)

# frontmatter 中
image: https://example.com/cover.jpg

2. 公共目录图片

以 / 开头，引用 public 目录下的文件：

public/
└── images/
    ├── posts/
    │   └── cover.jpg
    └── logo.png

![Logo](/images/logo.png)
![文章封面](/images/posts/cover.jpg)

3. 相对路径图片

相对于当前 Markdown 文件的位置：

src/content/posts/
└── my-post/
    ├── index.md
    ├── cover.png
    └── images/
        └── diagram.png

![封面](./cover.png)
![架构图](./images/diagram.png)

Tip

使用文件夹结构组织文章时，推荐使用相对路径引用图片，这样便于资源管理。

封面图片

在 frontmatter 中设置文章封面图片：

---
title: 我的文章
image: ./cover.png
---

封面图片会显示在：

• 文章列表卡片
• 文章详情页顶部
• 社交媒体分享预览

封面图片尺寸建议

用途	推荐尺寸	宽高比
文章封面	1200 × 630 px	1.91:1
OG 图片	1200 × 630 px	1.91:1
卡片缩略图	800 × 420 px	1.91:1

画廊功能

Mizuki 主题集成了 PhotoSwipe 灯箱组件，文章中的图片会自动支持画廊浏览：

• 点击图片可放大查看
• 支持左右滑动切换图片
• 支持鼠标滚轮缩放
• 支持触摸手势操作
• 自适应深色/浅色主题

画廊特性

1. 自动识别：文章内的图片自动支持画廊
2. 键盘导航：支持方向键切换、Esc 关闭
3. 全屏查看：支持全屏查看模式
4. 响应式：自适应不同屏幕尺寸

图片懒加载

Mizuki 主题默认对文章中的图片启用懒加载（Lazy Loading），只有当图片进入可视区域时才会加载。

优势

• 减少初始页面加载时间
• 节省用户带宽
• 提升页面性能得分

行为说明

• 首屏图片会立即加载
• 封面图片会优先加载
• 其他图片在滚动到附近时加载

图片优化

Mizuki 主题在构建时会自动优化图片：

自动优化

1. 格式转换：自动转换为 WebP 格式
2. 尺寸调整：生成多种尺寸以适配不同设备
3. 压缩：自动压缩图片以减少文件大小
4. 响应式：生成 srcset 实现响应式图片

图片格式建议

格式	适用场景	特点
JPG/JPEG	照片、复杂图像	文件小，有损压缩
PNG	图标、截图、透明图像	无损压缩，文件较大
WebP	通用场景	高效压缩，现代格式
SVG	矢量图标、图表	无损缩放，文件极小
GIF	简单动画	支持动画，文件较大

Tip

建议优先使用 WebP 格式，Mizuki 会在构建时自动处理格式兼容性。

图片标注

使用图片标题语法可以为图片添加说明文字：

![架构图](./architecture.png "Mizuki 主题架构图")

也可以使用 HTML 语法实现更复杂的图片说明：

<figure>
  <img src="./architecture.png" alt="Mizuki 主题架构图" />
  <figcaption>图 1：Mizuki 主题的整体架构设计</figcaption>
</figure>

响应式图片

Mizuki 主题自动处理响应式图片，为不同设备提供合适尺寸的图片：

• 桌面端：加载完整尺寸
• 平板端：加载中等尺寸
• 手机端：加载小尺寸

注意事项

1. 路径正确性：确保图片路径正确，否则图片无法显示
2. 文件名规范：图片文件名建议使用英文、数字和连字符
3. 文件大小：建议单张图片不超过 2MB，过大影响加载速度
4. 替代文字：建议为每张图片添加有意义的 alt 文本，提升可访问性和 SEO
5. 版权问题：使用远程图片时请注意版权和可用性
6. 备份资源：建议将图片资源与文章一起备份
7. WebP 优先：优先使用 WebP 格式，Mizuki 会自动处理兼容性