Markdown 图片：插入、调整大小与路径
Markdown 本身没有图片尺寸的语法。图片写成 ，需要指定宽度时，把这一张改成 HTML：<img src="/i/photo.png" width="320" alt="替代文字">。在妙言 V4.5.0 里，HTML 写法在预览中有效，因为预览允许原始 HTML，设置的宽度最多只会被限制在正文栏宽以内。图片放在笔记旁边并用相对路径引用，因为笔记一搬家，最先坏的就是路径。
图片语法、替代文字和标题
图片就是链接语法前面加一个 !。CommonMark 规范把方括号里的部分叫作图片描述，并说渲染成 HTML 时它通常用作 alt 属性；路径后面用引号写的标题会变成 title 属性，浏览器会把它显示为悬停提示。
描述要写给看不到图的人，写图里有什么，而不是「图片」或文件名。空描述  是合法的，妙言粘贴图片时写进去的就是空描述，笔记要公开发布的话，事后补上。
图片文件放在哪里
往笔记里粘贴图片，或者通过文件选择器插入图片文件时，妙言 V4.5.0 会把它复制到笔记所在文件夹下的 i/ 目录，目录不存在就先创建，然后在正文里写入 。文件夹名 i 是固定的，不是图片的文件放进 files/，方式相同。图片文件保留原名，只是把字母、数字、- 和 _ 以外的连续字符换成一个 -。粘贴的截图没有文件名，会存成 JPEG，用小写 UUID 当名字，重名时同样退回 UUID。移动端编辑器写进同一个 i/ 目录，所以同步之后在另一个应用里打开同一篇笔记也能找到图。
预览时妙言把 /i/harbor.jpg 解析到笔记所在的文件夹，而不是磁盘根目录，所以开头的斜杠在这里和网站服务器上的含义不一样。GitHub 的语法页给出的相对链接示例里，同一分支的 .md 文件用 /assets/images/electrocat.png，并建议仓库里的图片优先用相对链接而不是绝对链接。
预览怎么解析路径
对每个 <img>，预览先看 src。以 http:// 或 https:// 开头的地址不动。以 / 开头但不是 /i/ 的路径被当作系统绝对路径，文件存在才会使用。其余的，包括 /i/... 和 images/fig.png，都按笔记所在文件夹查找并转成 file:// 地址。文件不存在时，妙言会把整张图换成一个灰色方框，上面写着 Image Not Found。第一张图立即加载，后面的随滚动懒加载，段落里的图点击可以放大。
结果是这样。用 /i/harbor.jpg 或 i/harbor.jpg 的笔记，只要 i/ 文件夹跟着笔记走，在任何一台 Mac 上都能显示；用 /Users/you/Pictures/harbor.jpg 的笔记只有那台有这个文件的 Mac 能显示，换到别处就是占位框。
为什么笔记一搬图片就坏
- 只搬了
.md文件。i/文件夹留在原地，所有相对路径都指向空处。把文件夹和笔记一起搬，或者把整个笔记目录当作一个整体同步。 - 改了文件夹名或文件名。 笔记里的路径只是文字，不会有人替你更新。
- 路径是绝对路径。 它指的是某一台机器上的位置。
- 链接是远程的，页面搬了家或站点禁止盗链。 这时笔记依赖的是别人的服务器。
本地文件占磁盘，并且要跟着笔记搬；远程图片让笔记保持很小，但每次打开都要联网。想要远程链接又不想手动上传的话，妙言设置的「编辑器」页里有「上传服务:」，可选「无」、uPic、PicGo、Picsee 和 PicList。选 PicGo 或 PicList 时，妙言通过 HTTP 把粘贴的图片发给正在运行的工具，uPic 和 Picsee 则是直接调用装在 /Applications 里的应用来上传。上传成功时笔记里写入远程地址并删掉本地副本，失败时保留本地 /i/ 路径，并弹出上传失败的提示。
调整图片大小
CommonMark 和 GFM 都没有尺寸语法，可选方式都在核心之外：
| 方式 | 示例 | 适用范围 |
|---|---|---|
| HTML 属性 | <img src="/i/photo.png" width="320"> |
允许原始 HTML 的地方 |
| Pandoc 属性 | {width=50%} |
只有 Pandoc |
妙言的预览给每张图加了 max-width: 100% 和 height: auto。所以 width="320" 得到 320 像素宽的图，width="2000" 会被缩到栏宽，height 属性会被覆盖，比例保持不变。Pandoc 的 {width=50%} 写法妙言不解析，因为解析器只挂了表格、脚注、删除线和任务列表四个扩展，花括号会作为文字出现在图片后面。Pandoc 手册记录了这种属性写法，单位支持 px、cm、mm、in、inch 和 %。<img> 标签的 src 要用双引号，妙言只解析这种写法里的本地路径。
GitHub 的语法页记录了 ![]() 写法和 <picture> 元素，没有讲尺寸，所以在 README 里依赖 width 之前，先看一下预览。
还有一个边界是，文件缺失时，Image Not Found 的替换会丢掉整个标签，包括其中的 width。
PDF 和 HTML 导出里的图片
PDF 导出打印的是预览。它会等图片有了宽度，并把懒加载占位符换回真实地址，所以本地 /i/ 图片会出现在 PDF 里。细节见 在 Mac 上把 Markdown 转成 PDF。
V4.5.0 的 HTML 导出不一样。它渲染 Markdown 时没有走本地图片那一步，并加了 https://cdn.miaoyan.app/Resources/DownView.bundle/ 作为基础地址。所以从「下载」文件夹打开的文件找不到 /i/harbor.jpg 或 images/fig.png。远程图片可以正常加载。眼下要分享单个文件，就在笔记里用远程图片地址，或者导出 PDF。
检查结果
- 打开预览，确认每张图都显示，没有
Image Not Found方框。 - 把笔记和它的
i/文件夹复制到另一个位置再打开。 - 网络图片则断网看看还剩什么。
其他随软件而异的语法见 Markdown 语法速查与 GFM 差异。要在多台设备间共用笔记，文件夹需要整体同步，做法见 跨设备同步 Markdown 笔记的几种做法。
常见问题
纯 Markdown 能设置图片尺寸吗？
不能。CommonMark 规范只定义了描述、路径和标题。用 HTML 的 <img> 标签，文件由 Pandoc 渲染时也可以用它的属性语法。
用相对路径还是绝对路径？
相对路径。绝对路径指的是某一台机器的磁盘，GitHub 的文档也建议仓库里的图片用相对链接。
为什么我的图片显示 Image Not Found？
文件不在路径写的位置，通常是 i/ 文件夹没有跟笔记一起搬，或者文件被改了名。