Markdown 中图片使用的最佳实践

本指南围绕 Markdown 图片，说明如何让图片在代码仓库、文档站和导出文件中保持可访问、可迁移、可解析。目标不只是截一张图，而是得到清晰、可追溯到 Markdown 源文档、可以重复发布的素材。

文字、代码、表格和细线图表优先使用 PNG，以保持锐利；摄影背景可以考虑 JPEG，但压缩可能让小字号变软。多页阅读更适合 PDF，需要继续编辑的办公流程更适合 DOCX。不要把同一个格式硬塞给所有渠道。

1. 准备。 用 alt 文本说明图片传达的信息。
2. 预览。 使用目标渲染器能够解析的稳定 HTTPS URL 或仓库路径。
3. 导出。 在最终渲染器中测试引用式图片、标题、尺寸和深色模式对比度。

把下面的小样粘贴到渲染器。先用短内容确认排版与间距，再换成真实素材。

![Dashboard showing weekly signups](https://example.com/dashboard.png "Weekly signup dashboard")

![Architecture diagram][architecture]

[architecture]: https://example.com/architecture.svg "Service architecture"

CommonMark 定义可移植的 Markdown 核心语法；表格、任务列表和部分自动链接属于 GFM 扩展，不同渲染器可能表现不同。Mermaid 与 KaTeX 是由支持它们的渲染器处理的独立语法，并非 CommonMark 本身。必须在最终渠道测试。

• 信息型图片要写有意义的 alt 文本。
• 保持标题层级和阅读顺序清晰。
• 检查明暗主题下的对比度。
• 按实际展示尺寸检查图片。
• 把 Markdown 源码纳入版本控制。
• 内容变化后重新导出，不要在位图上补字。

避免小字号、过宽表格、未解释缩写、不稳定的远程图片，以及裁切过紧导致上下文消失。也不要声称所有 Markdown 引擎渲染完全一致：扩展语法和主题就是兼容边界。

本次更新中的事实边界已按以下一手资料核对：

• https://spec.commonmark.org/current/
• https://docs.github.com/en/get-started/writing-on-github
• https://markdowntoimage.com/

打开 MarkdownToImage，按最终宽度和主题测试示例。相关工作流可继续看 第一篇指南 和 第二篇指南。