跳转到主要内容
添加交互式页面,让读者可以点击浏览流程、使用小组件或观看你的产品如何运行。本指南介绍构建这类页面的四种基础元素:
  1. 以 React 组件形式写入页面的交互式组件。
  2. 使用浏览器脚本录制的产品或智能体会话的视频。
  3. 放在边框中、带有浅色和深色版本的截图。
  4. 用于展示状态、限制和对比的表格。
本指南示例中的产品、数字和步骤均为示例数据。

选择基础元素

交互式组件

交互式组件是在页面中使用 export const 声明、再通过 <RxJourney /> 这样的标签放置的 React 组件。将组件定义放在文件末尾,让内容可以从上到下顺畅阅读。请参阅 React 组件了解 MDX 环境支持的内容。

点击浏览流程

当流程有明确的先后顺序时,使用步骤器。每一步都说明由谁操作以及会发生什么。

试算你自己的数字

当答案取决于读者的输入时,使用计算器。在结果中展示公式,方便读者核对。

展示趋势

当读者需要在几个相关数据系列之间切换时,使用带切换按钮的图表。每个图表只回答一个问题。

计算器的工作原理

以下是计算器的完整源代码。套餐按钮、滑块和结果都读取状态,总额在渲染时计算。
usage.mdx

组件指南

  • 确保每种颜色在浅色和深色模式下都适用。文字和线条使用 currentColor 或 inherit,边框和填充使用 rgba(127,127,127,.25) 这样的半透明灰色,并只使用一种强调色。避免使用固定的黑色或白色。
  • 为最外层元素添加 className="not-prose",避免页面的排版样式改变组件内部的间距。
  • 将数据以常量形式写入组件。不要获取数据,也不要使用 localStorage、sessionStorage 或 cookie,因为它们在编辑器中会失败或不起作用。
  • 编写普通 JavaScript。TypeScript 类型注解会导致已发布站点上的整个页面出错。
  • 将链接放在组件周围的正文中。组件内部的链接在编辑器中无法跳转。
  • 为每个页面的组件使用一个简短的共享前缀,例如 Rx,避免与内置组件或彼此之间发生命名冲突。
  • 为按钮和输入框提供可见标签或 aria-label,并使用 aria-pressed 或 aria-current 标记所选选项。
  • 每个页面只放少量组件。编辑器一次最多运行 10 个组件,其余组件会暂停,直到滚动到可见区域。
  • 要在多个页面中使用同一个组件,请将其移动到 /snippets/ 中的文件并导入。请参阅可复用片段。

视频

当读者需要看到动态过程时,录制一段短视频:例如界面演示、部署完成的过程,或智能体处理任务的过程。静音并循环播放的视频可以当作动态截图使用。自托管的视频片段要短小,较长的视频请托管在 YouTube 等平台上。请参阅媒体了解何时使用视频以及如何控制文件大小。

使用脚本录制产品

浏览器脚本每次都能生成相同的视频,因此界面变化后可以重新录制。下面的 Playwright 脚本会在点击浏览流程的同时录制一个 WebM 文件:
record.mjs
让录制内容易于观看的技巧:
  • 每次操作后暂停约一秒,方便读者跟上变化。
  • 以带延迟的方式输入文字,而不是瞬间填充字段。
  • 视频时长控制在 30 秒以内。将较长的流程拆分为多个视频,并放在对应步骤旁边。
  • 使用示例账户和数据,切勿使用生产数据。

回放智能体会话

要展示智能体做了什么,可以记录它的会话并以视频形式回放。Claude Code 和 Codex 可以将会话写为 JSON 行,例如 claude -p "<task>" --output-format stream-json --verbose > session.jsonl。将消息和工具调用渲染为一个简单的终端风格 HTML 页面,然后用 Playwright 脚本录制该页面。回放会展示真实的命令以及智能体运行它们的顺序,而无需暴露实时终端。

截图

将截图放在 <Frame> 中,并添加说明读者应关注什么的标题。裁剪到屏幕中重要的部分。
要让截图保持最新,请使用脚本截图。使用与视频脚本相同的 Playwright 设置,调用 page.screenshot({ path: "images/settings-light.png" }),并在界面变化时重新运行。要生成深色版本,请使用 colorScheme: "dark" 创建上下文。请参阅图片和嵌入内容了解尺寸和缩放选项。

表格

表格承载读者会反复查看的细节:状态、限制、价格以及各选项的支持情况。先展示表格,并让周围的正文保持简短。 对于主要由表格组成的页面,请在 frontmatter 中设置 mode: "wide",让表格占满整个宽度。请参阅页面模式。

使用智能体构建这些页面

只要提供模式和数据,编码智能体就能很好地编写组件和录制脚本。让智能体参考本指南,然后描述你希望读者理解的内容。
Widget
Video
发布之前:
  • 使用 mint dev 或在编辑器中打开页面,分别检查浅色和深色模式。
  • 检查每个组件都能正常渲染,并能响应点击和键盘操作。
  • 将浏览器缩小到手机宽度,检查没有内容溢出。
  • 播放每个视频并打开每张图片。