Docs & Code Guide

Embed a diagram in GitBook: image by URL, the Embed block, and what the CDN changes

GitBook separates the two questions every diagram embed raises: how the block gets into the page, and where the pixels come from at view time. Insert an image by URL and GitBook keeps referencing your URL rather than importing a copy, which is the property a live diagram needs. Here is how the image block and the Embed block each behave, what the CDN in front of published sites means for freshness, and how Git Sync keeps the whole thing working as plain markdown.

Try it free
6 min readFor teams publishing product and engineering docs on GitBook

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

158/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The image block takes an external URL and keeps it external

GitBook's image block accepts either an upload or a URL. Uploads are copied into GitBook's storage and frozen; a URL stays a reference, and GitBook's own help center is explicit that an image inserted by URL relies on that URL to display, including breaking if the source disappears. That reliance is exactly the behavior a live diagram wants: the page shows whatever the endpoint serves at view time.

Insert one through the block menu, choose the URL option, and paste an endpoint that re-renders when the diagram changes. Sizing parameters are available when the default render does not fit the page width.

Image block URL (stays a live reference):
https://datadef.io/api/embed/my-platform-a1b2c3d4

Embed block URL (interactive, pan and zoom):
https://datadef.io/embed/my-platform-a1b2c3d4

In a Git Sync repo, the same image is plain markdown:
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4)

The Embed block for an interactive view

Paste a URL as an Embed block and GitBook renders it through iframely, the unfurling service that decides whether a URL becomes a rich frame or a plain link card. A page built for embedding renders as an iframe readers can interact with, and pointed at an interactive diagram page that means pan and zoom without leaving the docs, with a small attribution linking to the full diagram.

The Embed block earns its place on reference pages where readers inspect detail. For overview pages, the image block is lighter: one request instead of a framed page.

CDN caching, honestly

Published GitBook sites are served through a CDN, Cloudflare in front of custom domains, and a CDN between reader and origin can extend how long a cached image copy lives. The origin here serves the image with Cache-Control max-age=300 and an ETag tied to the last edit, so the intended freshness window is five minutes; a CDN layer that respects those headers re-validates on the same schedule.

The honest statement is: expect an edited diagram to show on your GitBook pages within minutes, and treat a hard refresh as the fix if an edge copy lingers a little longer. Nothing about the caching requires re-inserting the block or touching the page. The first render after an edit also takes a few seconds to produce before it is cached.

Git Sync writes plain markdown

Spaces synced to a repository store their pages as markdown files, and the image block round-trips to standard image syntax. That means the same line renders in the GitBook UI and in the repo view, survives edits from either side, and can be committed by an agent or CI job like any other file change.

Teams using Git Sync for SDK or API documentation get the compounding benefit: docs changes ride pull requests, and the diagram line in those files never needs another commit, because the pixels behind it follow the source. The wider workflow is in keep SDK docs in sync.

Keeping the diagram itself current

The block follows the diagram; the diagram still has to follow the system. Datadef ships an MCP server (registry name io.datadef/mcp), so an agent with repository access can update the diagram from what it reads in the code, after a merge, on a schedule, or on request during review. Datadef does not watch repositories and nothing regenerates unprompted; the loop is one agent call or CI command away. The key it presents exists on paid plans.

The visibility limit applies: embed URLs exist only while the project is shared public, and a private project 404s them across every GitBook page that used them. Confidential architectures should use uploaded exports instead, staleness accepted.

FAQ

How do I embed a diagram in GitBook?

Two ways: an image block pointed at an external URL such as https://datadef.io/api/embed/your-slug, which GitBook keeps as a live reference, or an Embed block with an interactive page URL, which renders as an iframe readers can pan and zoom. Both follow the source diagram.

Does GitBook copy external images or hotlink them?

An image inserted by URL stays a reference to that URL; GitBook documents that the page relies on the URL to display the image. Uploaded images are the opposite: copied into GitBook storage and frozen at upload time. For a diagram that should stay current, insert by URL.

How fast do diagram updates appear on a published GitBook site?

Within minutes in the normal case: the image is served with a five minute cache lifetime and an ETag tied to the last edit. Published sites sit behind a CDN, so an edge copy can occasionally linger slightly longer; a hard refresh fetches the current version. No page edit is ever needed.

Does the embed work with GitBook Git Sync?

Yes. Git Sync stores pages as markdown, and the image round-trips as standard syntax: ![alt](https://your-url). The same line renders in the GitBook UI and in the repository, and can be edited or committed from either side.

Can I embed a private diagram in GitBook?

Not as a live embed. The URLs exist only for projects shared public; making the project private turns them into 404s on every page that used them. For confidential content, upload a static export and accept that it no longer follows the source.