企业官网建设流程全解析

用Showboat搭建"可执行演示文档"时，showboat image命令负责把截图变成可复现的一部分：一条命令即可把图片复制进文档目录、生成uuid 命名的新文件名，并自动追加 markdown 图片引用与 alt 文本。本文带你走完「嵌入截图 → 理解 uuid 命名 → 控制 alt 文本」的完整流程，让演示文档既能读、又能被完整复现。

为什么演示文档需要「可复现的截图」

普通 markdown 文档里的截图有个通病：文件散落在各处，换个目录就引用失效。Showboat 的思路是让文档自己"携带"所有素材——showboat image会做三件事：

1. 把图片复制到文档所在目录，原图不动；
2. 用uuid 前缀 + 日期生成新文件名，杜绝重名冲突；
3. 在文档末尾追加「图片代码块 + 图片引用」，重建文档时原样保留。

配合init/note/exec/verify，一张截图就和可执行代码一样，成为文档可复现的一部分。

两种参数形式：纯路径与 markdown 图片语法

showboat image的第二种参数只有两种写法：

第二条命令建议始终用单引号包裹参数——原因在文末的避坑清单里说明。

深入理解：uuid 命名的生成规则

复制后的文件名遵循<uuid8位>-<YYYY-MM-DD>.<扩展名>格式，例如：

f4a2c9d1-2026-02-06.png

• uuid 取 8 位：由 exec/image.go 中的uuid.New().String()[:8]生成，保证多次插入同名图片互不覆盖；
• 日期取 UTC 当天：方便按时间直观排序；
• 目标目录固定为文档所在目录：复制路径由 cmd/build.go 的filepath.Dir(file)决定，文档走到哪里，图片就跟到哪里。

这套命名还带来一个好处：alt 文本派生时会去掉 uuid 前缀，见下一节。

深入理解：alt 文本如何派生

alt 文本的处理逻辑集中在 cmd/build.go：

• 传入markdown 图片引用时，解析出的 alt 文本被原样保留；
• 传入纯路径时，alt 文本由生成的文件名派生——去掉扩展名后得到uuid-日期串，最终写入图片引用作为 alt。

也就是说，想让截图在文档里有"人话"描述（比如"登录页截图"），直接用alt形式传入最省心。alt 解析函数 parseImageInput 还兼容了 shell 转义导致的\!前缀，解析结果由 markdown/writer.go 写回文档。

写入文档后的结构长什么样

执行showboat image demo.md 'Homepage screenshot'后，文档末尾追加的内容形如：

```bash {image} Homepage screenshot ``` Homepage screenshot

两个块分工明确：

• 带bash {image}标记的代码块记录"当初传入了什么"，让文档可重建；
• 其后的图片引用指向 uuid 命名的新文件，负责渲染展示。

文档结构定义见 markdown/blocks.go。

如何验证与重建含截图的文档

• showboat verify demo.md会跳过 image 代码块只重跑执行类代码块，截图不会被破坏；
• showboat extract demo.md能把image条目完整还原成命令行，从零重建整份文档。还原逻辑见 cmd/extract.go，其中 image 条目会被输出为showboat image <文件> 'alt'。

支持的图片格式与常见报错

格式白名单定义在 exec/image.go：

典型报错信息：

实战避坑清单

1. 始终用单引号：双引号里的!可能被 bash 的 history expansion 改写，单引号最安全；即便如此，parseImageInput 也会兜底兼容\!转义写法；
2. 插错了就 pop：showboat pop demo.md会连同代码块和图片引用一起移除，比手工编辑 markdown 更干净；
3. 想更直观地描述截图：优先使用alt形式，alt 文本比自动派生的文件名可读得多。

小结

一条showboat image命令，同时完成了「复制文件、uuid 命名、追加可重建引用」三件事，并自动处理好 alt 文本——这正是 Showboat "文档即可复现证明"理念的缩影。完整命令参考可在 help.txt 中查阅。