Jelly 的帮助文档里，有一个很容易被忽略的细节：截图不是人工打开页面、裁剪、上传，而是在构建时自动从运行中的应用里截出来。

这个点小，但不琐碎。帮助文档最常见的失真，往往不是文字全错，而是 UI 已经改了，截图还停在旧版本。按钮换了位置，弹窗改了文案，颜色和状态有一点差异，用户就会开始怀疑文档是不是还可信。

Jelly 的做法，是把截图维护从“发布后想起来再补”，改成“跟功能变更一起提交”。我更在意的是这条链路变化，而不是它用了哪一个截图库。

截图为什么最容易过期

帮助文档里的文字，改起来成本不高。打开 Markdown，改一句，提交即可。

截图麻烦得多。维护者要登录应用，准备演示数据，点到对应状态，截屏，裁剪，压缩，再把图片放回文档。每一步都不难，但每一步都会让人拖延。

对小型 SaaS 团队尤其如此。很多团队没有专职技术写作岗位，帮助中心常常由产品工程师顺手维护。功能上线时，工程师会优先处理代码、测试和发布，截图很容易变成“之后再说”。

问题就出在这里。

文档并不是一次写完就结束。只要产品 UI 在变，截图就会变成一种长期债务。Jelly 这套流程的核心判断，是把这笔债务放进开发者已经熟悉的构建动作里。

维护动作传统做法Jelly 的做法实际影响
声明截图靠人工记住哪张图要换写在 Markdown 的 HTML 注释里截图意图留在文档源文件中
生成截图手动打开页面、裁剪、上传构建时访问真实应用并截图减少重复操作
提交文档文字和图片常常分开处理截图可随 Markdown 一起更新更适合同一个 PR 处理
维护风险图片容易落后于 UI依赖稳定数据和选择器不是零维护，只是换了维护位置

这张表里最关键的一格，是“维护风险”。自动化不是把风险消灭，而是把风险显性化。截图坏了，最好在构建时暴露，而不是等用户照着旧图找不到按钮。

Jelly 具体怎么把截图接进 Markdown

Jelly 的帮助文章放在 public/manual/，按 basics、setup、advanced 等章节组织。Markdown 经 Redcarpet 处理后，再作为 Rails 应用里的 ERB 视图生成到 app/views/help/，同时生成面包屑和章节导航。

截图指令写在 Markdown 的 HTML 注释里。比如一条 SCREENSHOT 注释，会声明访问哪个演示团队、哪个页面、用哪种截图模式，以及匹配哪个 CSS selector。

紧接着下面的 image 标签，用来承接生成后的图片结果。也就是说，文档里仍然能看到“这里应该有一张什么图”，只是图片本身由构建任务更新。

构建入口是一条 rails manual:build。它会用 Rake 调 Capybara、Cuprite 和 headless Chrome，从运行中的 Jelly 应用里捕获截图，然后生成帮助页面。

这里要分清楚：这不是 AI 自动生成文档，也不是作者发布了一个通用截图产品。它更像 Jelly 内部给 Rails 应用补的一段文档基础设施。

截图模式有三类：

模式用途更适合的场景
element截取指定 DOM 元素表单、按钮组、设置面板
full_page捕获整页，可裁剪高度长页面、完整流程说明
viewport只截当前浏览器窗口接近用户实际看到的首屏

真正麻烦的不是按下截图键，而是让界面进入正确状态。

所以这套流程还支持一批处理选项：click 可以先点击按钮，打开表单或弹层；wait 给动画留时间；crop 裁掉无关区域；hide 临时隐藏开发工具栏、Cookie 横幅等干扰元素；torn 用 CSS clip-path 做撕纸边缘效果。

原文也提到，滚动到元素、处理 popover、裁掉多余内容这些边缘情况，花了不少工作。这一点很重要。它说明这套方案不是“写几行脚本就永远省事”，而是把复杂度前置到了可重复的脚本和配置里。

价值在小团队，边界也在小团队

Jelly 这件事最适合两类人看。

一类是 Web 产品工程师。以后改 UI 时，不只是改组件和测试，也要看帮助文档里有没有对应截图。更理想的动作是：改功能、改 Markdown、跑 rails manual:build，把生成后的图片一起提交。

另一类是技术文档维护者。过去他们可能要追着工程师要最新界面，现在至少可以把截图目标写进文档源文件。截图什么时候更新、更新失败在哪里，都更容易进入开发流程。

这和视觉回归测试有点像，但目标不同。

Playwright、Cypress、Storybook 的截图能力，常用来发现 UI 是否出现意外变化。它们关心的是“别变坏”。Jelly 这里关心的是“文档里的图要跟着真实界面变”。工具相近，问题不同。

限制也很现实。

这套流程依赖稳定的演示数据、可重复的登录状态、可预测的前端动画，以及不频繁变化的 CSS selector。如果产品大量依赖第三方内容、个性化数据或 A/B 实验，自动截图可能会引入新的维护成本。

接下来真正该看的，不是它能不能再多截几张图，而是三个变量：截图指令半年后还好不好读，CSS selector 改动后好不好修，演示数据变复杂后还能不能稳定构建。

如果这三件事能稳住，截图进入构建链路就不是花活。它会变成小团队维护帮助中心的一种低成本纪律。

文档系统最怕的是“差一点”。图差一点，字差一点，状态差一点，用户就会少一点信任。Jelly 这套做法没有承诺零维护，但它把维护放回了开发者每天都会经过的路上。