图片
图片只有一种写法：Markdown 的 。独立成段的图片可以在下一行跟一行 {…} 属性，成为带图注的 figure、缩放候选、编号图或经 Hugo 处理的派生图。主题没有图片 shortcode。
最简例子
这张图与本页放在同一目录（页面包）中，主题读取它的固有尺寸并写入 width/height，页面加载时不发生跳版；所有图片懒加载。替代文字供屏幕阅读器与搜索引擎使用，应当始终填写；空 alt 表示装饰性图片，缩放会跳过它。
图片来源
来源按以下顺序解析，写法相同：
| 放法 | 源码里怎么写 | 适合 |
|---|---|---|
与页面同目录（页面包 index.md + 图片） |
 |
只有这一页用的截图；随页面一起移动、翻译共用 |
全局资源 assets/images/… |
 |
多页共用、还要做处理（缩放 / 裁切）的图 |
静态目录 static/images/… |
 |
不需要处理的大图、下载物；主题拿不到尺寸时可以用 width/height 补 |
| 远程 URL |  |
少用：构建期不会下载，也不能处理 |
相对路径先按页面资源、再按全局资源查找，都找不到时按静态路径原样输出；主题不检查静态路径与远程 URL 是否存在。只有要求处理（command=）的图找不到资源时才构建失败。
行内与块级
位于文字中间的是行内图片，渲染为一个 <img>，不能带属性；独立成段的是块级图片，可以带属性行。
这一枚小图 
夹在句子里，是行内图片。
行内图片按自身尺寸显示（这里是 50×32）。没有固有尺寸的 SVG 行内插入时会被拉伸到容器宽度，SVG 应作为块级图片使用并给出 width/height。
块级图片依赖站点设置 markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false（本站已配置；见配置总览）。缺少它时 Goldmark 会把独立图片包进 <p>，属性行也会被当作正文。
图注
属性行加 caption="…"，图片渲染为 <figure> + <figcaption>。图注是纯文本，不解析 Markdown。
Markdown 里的 "标题" 保持原义（悬停提示），不会成为图注。
尺寸
width/height 是正整数，覆盖资源自身的尺寸：为静态或远程图片提供占位框以避免跳版，或把大图缩小显示（浏览器缩放，不改文件）。
处理型图片
页面资源与全局资源可以在构建期由 Hugo 处理：command 与 options 必须同时给出，命令是 Fit Resize Fill Crop 之一，选项是 Hugo 的图片处理字符串。渲染出的 src 是派生图；启用缩放时对话框打开原图。
静态路径、远程 URL 与 SVG 不能处理，对它们写 command 会构建失败。选项语法（锚点、质量、格式转换，如 300x150 webp q80）见 Hugo 图片处理。
链接图片
两种写法，用途不同：
- 没有图注、图片本身是链接：用 Markdown 的链接包图
[](href)。 - 有图注的 figure 整体可点：属性行加
link="…"（必须同时有caption或num）。
带链接的图不参与缩放。没有图注只写 link= 会构建失败，报错中提示改用 [](…)。
编号图
编号图用于书籍与长篇手册：属性行加 num，可选 #id。编号是作者书写的字符串（2-1、3.4），主题不自动计数；图注前加本地化的「图 2-1」前缀，#id 缺省为 fig-<num>。正文用普通链接 [图 2-1](#fig-2-1) 或 xref shortcode 引用；全书图目录见书籍出版。
见图 2-1。
编号图可以同时是处理型图片（num + command），也可以带 link。
缩放
图片缩放默认关闭。站点开启后，块级图片、figure、画廊中带 alt 的图成为可点击的按钮，在原生 <dialog> 中查看大图（Esc 关闭，焦点回到原处）。本页在 front matter 中开启了它，上面的图都可以点击。
不缩放的图：行内图、alt 为空的装饰图、带链接的图、data-no-zoom 标记的图。运行时只在页面确有候选图时加载；打印 / Markdown / RSS 中没有对话框。
深浅色图片
主题没有按深浅色切换图片的参数。需要两张图时，各写一个 class，在站点 CSS 中按 [data-bs-theme="dark"] 显示其一：
class 由主题原样透传，供站点 CSS 使用。
输出形态
| 输出 | 呈现 |
|---|---|
| HTML | 行内 <img>；块级 <img class="td-image">；有图注 / 编号时 <figure class="td-figure"> + <figcaption>；缩放候选带 data-td-image-zoom |
| 打印 | 同 HTML，去掉缩放控件 |
| Markdown | 原样输出  与属性行 |
| RSS | 图片 src 改为绝对地址；无缩放 |
参数参考
属性行 {…}（块级图片之后紧接的一行）：
style、on*、alt、title、src 与其它任何键出现在属性行都会构建失败（alt、title、src 属于 Markdown 图片本身）。
限制与常见问题
- 图注不含 Markdown：所有公开字符串参数都是纯文本；富文本说明写在图片下方的段落中。
title不是图注：的c是悬停提示。- 处理型图片只对资源生效：
static/中的图需要处理时移到页面包或assets/。 - 构建期不下载远程图片。
- 缩放不支持拖拽、平移、上一张 / 下一张；一组相关图片使用画廊。