Embed diagrams in Google Docs: By URL is a snapshot, and the honest workarounds

When you insert an image by URL, Google Docs downloads it at insert time and stores that copy with the document. The URL is not retained as a live reference: edit the image at the source and the Doc keeps showing the version from insert day. This is deliberate on Google's side, documents are self-contained, but it means the mechanism that keeps a diagram current in Notion, Confluence, or a docs site simply does not exist in Docs.

It is worth saying plainly because the same URL behaves differently elsewhere: paste a live image URL into a wiki that hotlinks it and the page follows the source; paste it into a Google Doc and you have a snapshot. The staleness is invisible, too. The copied image looks identical to a live one until someone compares it against the system and finds a service that no longer exists.

The lightest honest pattern: keep a snapshot in the Doc for reading flow, and put a link to the live diagram directly under it, labeled with the date the snapshot was taken. Readers get context without leaving the page, and one click gets them the current truth. The date label does real work here: it converts an invisible staleness into a visible one, and a reader seeing a six month old date knows to click before trusting.

In the Doc, under the pasted diagram:

Live version: https://datadef.io/embed/my-platform-a1b2c3d4
Snapshot taken: 2026-08-12

For long-lived Docs that many people read, a small Apps Script can re-fetch the image and swap it in place. Run it manually or on a time-driven trigger, and the Doc carries a snapshot that refreshes itself on your schedule. This is the closest Docs gets to a live embed, and it is honest about what it is: a scheduled re-copy, not a live reference.

function refreshDiagram() {
  const URL = 'https://datadef.io/api/embed/my-platform-a1b2c3d4';
  const doc = DocumentApp.openById('YOUR_DOC_ID');
  const body = doc.getBody();
  const images = body.getImages();
  if (images.length === 0) return;
  const old = images[0]; // first image in the doc: the architecture diagram
  const blob = UrlFetchApp.fetch(URL).getBlob();
  const parent = old.getParent();
  const index = parent.getChildIndex(old);
  old.removeFromParent();
  parent.asParagraph().insertInlineImage(index, blob);
}

If the artifact does not have to be a Doc, Google Sites embeds URLs in-page, which Docs cannot. An internal Sites page carrying the interactive diagram gives readers pan and zoom and always shows the current version. Teams often land on a split: Docs for the narrative that does not change, a Sites page or the diagram link itself for the picture that does.

All three workflows lean on the source diagram being correct, and Docs being in the picture changes nothing about that maintenance. When the architecture moves, update the diagram by hand, or hand the job to an agent that has the Datadef MCP server, registry name io.datadef/mcp, among its tools: it reads the repository and makes the edit, after which a Sites embed is current within minutes and the next Apps Script run refreshes the Doc snapshot. Datadef triggers nothing itself and detects no code changes; the agent needs an API key, which paid plans include. The embed and image URLs exist only for projects shared public.

Why documents drift from reality in the first place, and why image snapshots drift worst, is covered in why documentation goes stale. Google Docs is simply the environment where the drift is least visible, because the snapshot never looks broken, only wrong.

• Embed diagrams in Markdown
• Embed diagrams in Dropbox Paper
• Embed diagrams in Notion
• Why documentation goes stale