垦荒学园
  • 中文

      • Markdown 图片

      在文档中添加图片可以让内容更加生动和易于理解。Markdown 提供了简单的图片插入语法，支持本地图片、网络图片等多种方式。本章将详细介绍 Markdown 图片的各种用法。

      基本图片语法

      语法格式

      ![替代文本](图片URL)
![替代文本](图片URL "可选标题")

      示例

      ![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

![带标题的图片](https://example.com/image.jpg "这是图片标题")

      效果：

      GitHub Logo

      带标题的图片

      图片语法说明

      替代文本（Alt Text）

      替代文本在图片无法加载时显示，对 SEO 和无障碍访问很重要：

      ❌ ![图片](image.jpg) - 缺少描述
✅ ![一只可爱的猫咪](cat.jpg) - 有意义的描述
✅ ![架构图](architecture.png) - 描述图片内容

      图片标题

      鼠标悬停在图片上时显示：

      ![产品截图](screenshot.jpg "点击查看大图")

      引用式图片

      语法

      ![替代文本][图片引用]

[图片引用]: 图片URL "可选标题"

      示例

      这里有两张图片：

![Logo][logo]
![图标][icon]

[logo]: https://github.com/github.png
[icon]: https://example.com/icon.png

      效果：

      这里有两张图片：

      Logo 图标

      引用式图片的优势

      • 集中管理：图片 URL 统一定义
      • 易于维护：修改 URL 只需改一处
      • 可复用：同一图片多次使用
      • 文档清晰：内容不会被 URL 打断

      本地图片

      相对路径

      ![本地图片](./images/photo.jpg)
![子目录图片](./assets/icons/logo.png)
![上级目录图片](../photos/album.jpg)

      绝对路径

      ![绝对路径](/home/user/project/images/pic.jpg)

      网络图片

      直接链接

      ![网络图片](https://example.com/image.jpg)
![GitHub 图标](https://github.com/github.png)

      稳定的 CDN

      ![CDN 图片](https://cdn.example.com/images/photo.jpg)

      图片链接

      将图片作为链接

      [![图片描述](图片URL)](链接URL)

      示例

      [![访问 GitHub](https://github.com/github.png)](https://github.com)

[![点击查看大图](./thumbnail.jpg)](./large.jpg)

      效果：

      访问 GitHub

      HTML 图片标签

      更灵活的控制

      <img src="image.jpg" alt="描述" width="300" height="200">

      带样式的图片

      <img src="image.jpg" alt="描述" style="border-radius: 10px; box-shadow: 0 2px 5px rgba(0,0,0,0.3);">

      响应式图片

      <img src="image.jpg" alt="描述" style="max-width: 100%; height: auto;">

      图片尺寸控制

      Markdown 语法限制

      标准 Markdown 不直接支持尺寸调整，需要使用 HTML：

      <!-- 固定尺寸 -->
<img src="image.jpg" width="500" height="300">

<!-- 宽度自适应 -->
<img src="image.jpg" width="50%">

<!-- 最大宽度 -->
<img src="image.jpg" style="max-width: 800px; width: 100%;">

      GitHub Flavored Markdown

      GitHub 支持使用 | 分隔符：

      ![图片](image.jpg|300)

      图片对齐

      HTML 方式

      <!-- 左对齐 -->
<img src="image.jpg" align="left">

<!-- 右对齐 -->
<img src="image.jpg" align="right">

<!-- 居中 -->
<center>
    <img src="image.jpg">
</center>

      使用 div 容器

      <div style="text-align: center;">
    <img src="image.jpg" alt="居中图片">
    <p>图片说明</p>
</div>

      图片说明

      基本说明

      ![图片](image.jpg)

*图片 1：这是一个示例图片*

      带编号的说明

      ![架构图](architecture.png)

**图 1**：系统架构示意图

      并排图片的说明

      | 图1：组件A | 图2：组件B |
|----------|----------|
| ![图A](a.jpg) | ![图B](b.jpg) |

      图片优化建议

      1. 选择合适的格式

      格式适用场景
      JPG照片、复杂图像
      PNG图标、透明背景
      SVG图标、矢量图形
      WebP现代浏览器、优化压缩
      GIF简单动画

      2. 压缩图片

      使用工具压缩图片大小：

      • TinyPNG
      • ImageOptim
      • Squoosh

      3. 使用适当尺寸

      ✅ ![缩略图](thumb-200x200.jpg)
✅ ![中等图片](medium-800x600.jpg)
❌ ![超大图片](huge-4000x3000.jpg)

      4. 提供替代文本

      ✅ ![产品截图](screenshot.jpg "产品功能展示")
❌ ![图片](image.jpg)

      图片存储最佳实践

      目录结构

      project/
├── docs/
│   └── README.md
├── images/
│   ├── screenshots/
│   ├── diagrams/
│   └── icons/
└── assets/
    └── logos/

      命名规范

      <!-- 推荐 -->
![系统架构图](./images/diagrams/architecture.png)
![用户界面截图](./images/screenshots/ui-2024.png)

<!-- 不推荐 -->
![图片1](./img1.jpg)
![screenshot](./123.png)

      版本控制

      • 大文件使用 Git LFS
      • 压缩图片后再提交
      • 考虑使用 CDN 或图床

      图片托管方案

      1. 本地存储

      ![本地图片](./images/photo.jpg)

      优点： 完全控制、不依赖外部服务
      缺点： 增加仓库大小、加载速度慢

      2. 图床服务

      ![图床图片](https://img.example.com/photo.jpg)

      常用图床：

      • Imgur
      • Cloudinary
      • 七牛云
      • 阿里云 OSS
      • GitHub 仓库

      3. CDN 加速

      ![CDN 图片](https://cdn.example.com/image.jpg)

      图片占位符

      使用占位符服务

      ![占位符](https://via.placeholder.com/300x200?text=Placeholder+Image)

      常用占位符服务：

      • Placehold.co
      • Placeholder.com
      • Dummyimage.com

      自定义占位符

      ![待添加图片](./images/coming-soon.png)

      图片加载优化

      懒加载

      <img src="image.jpg" loading="lazy" alt="描述">

      延迟加载

      默认显示缩略图，点击加载高清图：

[![缩略图](thumb.jpg)](large.jpg)

      特殊图片类型

      SVG 图片

      ![SVG 图标](./icons/logo.svg)

      GIF 动图

      ![动画演示](./animation.gif)

      数据 URI 图片

      <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="内嵌图片">

      不同平台的图片支持

      GitHub

      • 支持本地和远程图片
      • 图片托管在仓库中
      • 自动生成缩略图

      GitLab

      • 支持图片拖拽上传
      • 可以直接粘贴图片

      Typora

      • 支持拖拽插入图片
      • 可以复制粘贴图片
      • 自动管理相对路径

      VS Code

      • 需要使用预览插件
      • 支持相对路径链接
      • 图片悬停显示

      图片安全

      防止盗链

      • 使用引用式图片
      • 考虑添加水印
      • 使用可靠的图床

      验证来源

      <!-- 来自可信来源 -->
![官方文档](https://docs.python.org/images/logo.png)

<!-- 未知来源谨慎使用 -->
![未知图片](https://random-site.com/image.jpg)

      实战示例

      文章插图

      ## 产品介绍

我们的产品具有以下特点：

![产品界面](./images/product-ui.jpg)

如上图所示，界面简洁直观，易于上手。

      技术文档流程图

      ## 工作流程

系统执行流程如下：

![流程图](./images/diagrams/workflow.png)

**图 1**：系统工作流程示意图

      教程步骤图

      ### 步骤 1：安装软件

![安装界面](./images/screenshots/install.png)

如上图，点击"下一步"继续安装。

### 步骤 2：配置设置

![配置界面](./images/screenshots/config.png)

完成配置后，点击"保存"。

      图片画廊

      ## 作品展示

| 作品 1 | 作品 2 | 作品 3 |
|--------|--------|--------|
| ![作品1](./gallery/work1.jpg) | ![作品2](./gallery/work2.jpg) | ![作品3](./gallery/work3.jpg) |

*图 1：精选作品展示*

      常见问题

      Q: 图片无法显示？

      A: 检查以下几点：

      • URL 是否正确
      • 文件是否存在
      • 权限是否正确
      • 网络是否可访问

      Q: 如何在 Markdown 中调整图片大小？

      A: 使用 HTML 标签：

      <img src="image.jpg" width="500">

      Q: 图片加载慢怎么办？

      A:

      • 压缩图片大小
      • 使用 CDN
      • 使用懒加载
      • 提供 WebP 格式

      Q: 如何批量插入图片？

      A: 使用脚本或编辑器插件自动化处理。

      小结

      本章详细介绍了 Markdown 中图片的使用方法：

      • 基本语法：!alt 格式
      • 引用式图片：集中管理图片 URL
      • 本地和网络图片：多种图片来源
      • 尺寸和对齐：使用 HTML 控制
      • 优化建议：格式选择、压缩、命名
      • 最佳实践：合理的目录结构和命名

      掌握图片的各种用法，可以让你的文档更加生动和专业。

      下一步： 学习 Markdown 表格 的创建方法。