文档与输出图像自动同步

在软件技术文档中，正文中说明的命令示例与实际粘贴的终端执行结果截图经常出现脱节。 随着工具版本迭代，如果人工手动重新打开终端截屏、保存并逐一替换文档中的图片引用，极易发生遗漏与陈旧失效。 此外，像 Astro 这样的静态网站生成器（SSG），如果文档内引用的图片在本地缺失便会直接中断构建，这在处理仅能在特定操作系统或 CI 环境中执行的命令截图时会极大阻碍本地开发。

console2svg batch markdown 可以自动检测 Markdown 或 MDX 文件中的注释标记，通过伪终端（PTY）执行对应命令，并将生成的图像无缝回写至文档中。 它彻底省去了人工截图与整理的繁琐工作，使技术文档的正文说明与实际执行结果始终保持同步。

基本同步工作流

在文档中嵌入终端图像包含两个步骤：插入标记以及执行批量同步命令。

1. 在文档中希望呈现终端截图的位置插入 <!-- c2s:: [command] --> 格式的注释标记：

   example.md

   执行 `dotnet --info` 命令将得到如下输出：
   
   <!-- c2s:: dotnet --info | head -n10 -->

2. 指定文档所在输入目录与静态资源输出目录，执行 batch markdown 命令：

   Terminal

   console2svg batch markdown -i ./docs -o ./assets

3. 该命令会自动解析标记，捕获命令的终端输出并生成 SVG 图像保存至输出目录。 同时，原 Markdown 文件也会被自动修改，在标记的正下方插入对应的图片引用：

   example.md

   执行 `dotnet --info` 命令将得到如下输出：
   
   <!-- c2s:: dotnet --info | head -n10 -->
    ![dotnet --info | head -n10](assets/generated/a1b2c3d4.svg)

如果标记正下方已存在图片引用，命令不会重复插入链接，而只会直接覆盖更新目标图片文件。

路径解析与引用前缀解耦

在不同网站构建体系中，图像文件在磁盘上的实际存放路径往往与 Markdown 中应书写的 Web URL 路径不同。 --link-base 选项正是用于弥合这一差异：

Terminal

console2svg batch markdown \
  -i ./docs \
  -o ./my-site/public/assets \
  --link-base /assets

例如在 Astro 中，存放在 /public/assets/ 下的静态资源，在 Markdown 中需要写成 /assets/filename.svg 这样的根相对绝对路径。 通过使用 -o 指定实际落盘路径，配合 --link-base 指定 Web 访问路径，即可灵活适配任意静态资源流水线。

资源版本管理策略

生成出的图像是否纳入 Git 版本控制，取决于项目整体规模与仓库容量维护策略。

将图像纳入 Git 版本控制

当文档图像数量适中且期望仓库保持自包含时，可将生成的图像文件与更新后的 Markdown 直接一并提交至 Git：

Terminal

console2svg batch markdown -i docs -o assets
git add docs assets
git commit -m "docs: 更新命令执行截图"

这种模式下，新克隆代码仓库的协作者本地即拥有全部图像资产，无需执行额外构建步骤即可直接在本地预览完整的文档站点。

将图像排除在 Git 管理之外

当文档图像体量庞大、为避免 Git 仓库急剧膨胀时，可将图片输出目录写入 .gitignore，并在 Markdown 中仅保留标记而不写入图片链接：

example.md

<!-- c2s:: echo "Hero Image" -->

不手动书写图片链接，将资源管理全权委托给自动化流水线。

在文档部署阶段，由 CI 流水线运行 batch markdown 实时生成图像并一并发布为静态资源：

deploy.sh

console2svg batch markdown -i ./docs -o ./public/assets
npm run build

然而在此模式下，全新克隆的代码库缺少图像，会导致 SSG 本地构建报出缺图错误。 该问题可通过后文介绍的 batch restore 或 --placeholder 得到有效解决。

远端静态资源同步与本地构建支持

在仅由 CI 生成图像的架构中，可利用以下辅助功能保障顺畅的本地开发体验。

利用 batch restore 还原远端资源

batch markdown 在生成图像时，会在输出目录下自动生成名为 assets.json 的静态资源清单文件：

• 文件夹assets/

  • 文件夹generated/

    • a1b2c3d4.svg
  • assets.json

将此清单文件连同构建产物一并部署到 Web 服务器后，本地开发者即可通过 batch restore 快速下载已生成的图像：

Terminal

console2svg batch restore -o ./assets \
  https://example.com/assets/assets.json

若需要清理本地存在但远端清单中已被废弃的无用图像，可附加 --prune 参数进行清理。

利用 --placeholder 确保本地立即构建

若无需通过网络下载全部图像，仅希望让本地文档站点顺利完成构建并预览排版，可使用 --placeholder 选项：

Terminal

console2svg batch markdown -i ./docs -o ./assets --placeholder

该选项会跳过所有真实的命令执行，直接为每个标记引用的图片路径创建大小为 0 字节的占位空文件。 这样既满足了 SSG 对引用文件必须存在的要求，又便于快速投入文字编写与布局调整。

命令哈希带来的资源去重

标记中所声明的命令、参数及尺寸完全一致时，即便它们分散在不同文档中，也会基于内容哈希共享同一个生成的图像文件。

doc-a.md

<!-- c2s:: -w 100 -h 12 --- dotnet --info | head -n10 -->

doc-b.md

<!-- c2s:: -w 100 -h 12 --- dotnet --info | head -n10 -->

这一特性在构建多语言文档时尤为高效。 当英文、中文及日文文档展示完全相同的命令执行过程时，各语言页面仅需保留相同标记，实际输出的图像文件只有一份，极大节省了存储与构建耗时。

标记的高级配置语法

除基础的内联命令执行外，标记还支持丰富的窗口外观设置、输出格式选择及生命周期钩子自动化。

窗口外观与格式选项

在分隔符（--）前，可以直接指定与 console2svg capture 通用的全部配置选项：

example.md

<!-- c2s:: -w 100 -h 10 -d macos -t nord --format png -- dotnet --version -->

指定 --format png 时将生成 PNG 格式位图，并在 Markdown 中自动插入 .png 扩展名的链接。

基于 YAML 控制执行生命周期

若需要在执行命令前准备环境，或在执行后清理临时文件，可在标记内部以 YAML 格式定义完整的生命周期流程：

example.md

<!-- c2s:: -w 100 -h 10 -d macos
setup:
  dotnet build
capture:
  dotnet run --no-build
teardown:
  rm -f temporary-file
-->

setup 中的脚本仅用于环境初始化，其输出不会进入截图画面。 最终图像仅捕获 capture 所声明命令的执行结果。 无论命令执行成功与否，teardown 中声明的清理脚本都会在最后无条件执行。

引用命名代码块内容

若希望直接执行文档中展示的示例代码块并截图，可在代码块上添加 c2s-id，并在标记中通过 {code:id} 进行引用：

example.md

```csharp c2s-id=program
Console.WriteLine("Hello from C#!");
```

```bash c2s-id=run
dotnet run app.cs
```

<!-- c2s::
setup: |
  cat > app.cs <<'EOF'
  {code:program}
  EOF
capture: "{code:run}"
teardown: rm -f app.cs
-->

该语法避免了技术说明代码与可执行脚本的双重维护问题，当代码块内容被修改时，终端图像也会自动保持同步。

安全注意事项

标记中定义的 setup、capture 与 teardown 脚本将在宿主机的 Shell 环境中直接运行。 严禁对不可信的 Markdown 文件或来自未经审查的外部 Pull Request 文件盲目执行 batch markdown。 在 CI 环境中配置自动化时，请务必严格限制分支权限与执行凭证。