如何把实时更新的架构图嵌入文档、Notion、Confluence 和 GitHub

每一张以截图形式进入 Wiki 的架构图，都开启了一场缓慢的倒计时。系统变了，有人更新了源文件，可新人入职指南、运维手册和设计文档里的截图还是原来的样子。半年后，没有人再相信其中任何一张。

解决办法说起来很简单：只维护一张实时图，让每个页面都指向它。本文按场景逐一说明具体做法：文档站点、Notion、Confluence、GitHub README 和聊天工具，以及页面无法显示实时图时该怎么办。更完整的工作流程，请参阅不会过时的架构图。

展示图的三种方式

尽量使用前两种，只有在不允许任何实时内容的地方才用导出。

获取链接和嵌入代码

在 Archboard 中打开图，选择分享：

1. 打开任何拥有链接的人，复制分享链接。观看者无需账号即可实时观看这张图，但无法编辑。
2. 如果你用的是 Pro，打开嵌入并复制嵌入代码。代码如下所示：

<iframe src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN" width="100%" height="480" style="border:0;border-radius:8px;" allowfullscreen loading="lazy" title="Archboard diagram"></iframe>

你可以随时重新生成链接或嵌入代码，旧的会随之失效；也可以关闭分享，观看者会立即断开。

把实时图放到公开页面之前，有一点需要了解：观看者会实时看到编辑过程，还能看到在编辑器中打开这张图、拥有编辑权限的人以及正在处理它的 AI 智能体的名字和光标。观看者自己的名字永远不会显示。

文档站点

纯 HTML、Jekyll、MkDocs 和大多数静态站点生成器。 把嵌入代码粘贴到图要出现的位置即可，它们的 Markdown 支持原始 HTML。Hugo 默认会忽略 Markdown 中的原始 HTML，所以要把 iframe 放进 shortcode，或者在站点配置中设置 markup.goldmark.renderer.unsafe = true。

Docusaurus 和其他 MDX 站点。 MDX 需要的是 JSX，所以 style 属性必须是对象，属性名也要用 camelCase：

<iframe
  src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN"
  width="100%"
  height="480"
  style={{ border: 0, borderRadius: 8 }}
  allowFullScreen
  loading="lazy"
  title="Checkout service architecture"
/>

两个小习惯能方便读者：设置一个不用滚动就能完整显示图的高度；给每个 iframe 加上描述图内容的 title，屏幕阅读器会读出它。

Notion

输入 /embed，选择 Embed，然后粘贴嵌入代码中 src 属性里的 URL（不是整个 iframe 标签）。Notion 通过自己的嵌入服务加载嵌入内容；如果某个页面无法内嵌显示，Notion 会改为显示错误。这时，把分享链接粘贴为书签即可：点一下就能打开实时图。

Confluence

Confluence Cloud 的编辑器不接受原始 HTML 或 iframe 代码。粘贴分享链接，Confluence 会把它转成链接或卡片。如果你的组织允许使用 Marketplace 应用，可以借助 iframe 或 HTML 宏应用在页面内显示嵌入内容。

Confluence Data Center 提供一个管理员可以启用的 HTML 宏。它允许任何有编辑权限的人向页面添加任意 HTML 和 JavaScript，因此很多组织都让它保持关闭。在以此为前提做规划之前，先问问你的管理员。

GitHub README 和仓库中的 Markdown

GitHub 不会渲染 Markdown 中的 iframe，所以 README 里无法实时嵌入。最好的替代方案是把导出的 SVG 提交到代码旁边，并链接到实时图：

[![Checkout architecture](docs/architecture.svg)](https://getarchboard.app/s/YOUR_SHARE_TOKEN)

读者在 README 中看到图片，点击即可打开最新版本。在 pull request 模板里加上“图的导出更新了吗？”；如果希望把图的变更当作数据来评审，也把 JSON 导出一并提交。

Slack、Teams、Jira 和邮件

粘贴分享链接即可。它总是打开最新版本，所以讨论串里的旧消息不会指向一张旧图。

让它持续有效的做法

• 一张图，多个链接。 永远不要为了“给 Wiki 做一个版本”而把图复制到另一个文件里。
• 把标题、负责人和最近评审日期写在画布上。 嵌入和链接展示的是画布，而不是你页面的元数据。
• 有意识地分享。 公开页面上的链接或嵌入会让这张图公开。内部架构要放在内部页面上，链接一旦泄露就重新生成。
• 把导出当作后备方案，而不是习惯。 每一次导出都是一份可能过时的副本。

下面是整套做法在一张画布上的样子：

在 Archboard 中设置

打开任意一张图，选择分享并打开链接；如果你用的是 Pro，再打开嵌入。如果你要为文档新建一张图，模板和示例能帮你快速上手；上面这张图用了基础节点包中的 9 个方框，在 Free 方案范围之内。

常见问题

Free 方案可以嵌入图吗？ Free 包含带品牌标识的分享链接。iframe 嵌入属于 Pro 和 Enterprise。

观看者需要账号吗？ 不需要。任何拥有链接或能打开嵌入页面的人都可以实时查看这张图，但不能编辑。

之后可以停止分享吗？ 可以。重新生成链接或嵌入代码，旧的就会失效；关闭分享，观看者会立即断开。

导出的 SVG 会随图的变化而更新吗？ 不会。导出的是副本。图有变化时请重新导出，或者尽可能使用链接或嵌入。

为什么我的嵌入在 Notion 或 Confluence 中显示错误？ 这两个工具都会控制哪些内容可以嵌入。可以改用分享链接，以书签或卡片的形式插入，或者向管理员咨询嵌入类应用。

免费开始 — 1 个席位，无需信用卡。