Embed a diagram in ReadMe.com docs: image by URL, embed blocks, and the OpenAPI pages

ReadMe renders its own markdown flavor, and pages written in the old editor may still contain magic blocks: JSON payloads between [block:...] and [/block] markers that describe rich components. ReadMe Refactored moved the format to MDX, and its processor transpiles the legacy block JSON for backwards compatibility, so both syntaxes keep rendering.

For a diagram, the practical takeaway is that a plain markdown image with an external URL works in every generation of the format, and pointed at a live endpoint it keeps the page current without edits: the image re-renders when the diagram changes, with a five minute cache lifetime.

![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4)

<!-- Legacy magic block form, still rendered for older pages: -->
[block:embed]
{
  "url": "https://datadef.io/embed/my-platform-a1b2c3d4",
  "title": "Platform architecture",
  "iframe": true,
  "height": "560"
}
[/block]

ReadMe's embed block renders a URL inside the page, and with the iframe option it frames the target directly, height configurable. Point it at an interactive diagram page and readers pan and zoom inside your developer hub, useful on the architecture overview where integrators work out how your system fits theirs.

The framed page must allow embedding. The Datadef embed page does, rendering chrome-less with a small attribution link to the full diagram. For most other pages the plain image is the lighter choice, and freshness is identical either way.

A ReadMe hub has two kinds of pages with different authoring models. Guides and landing pages are free-form: you write them, so images and embed blocks go wherever you want. API reference pages are generated from your OpenAPI spec, and their prose comes from the spec itself, description fields on the info object, operations, and parameters, which ReadMe renders as markdown.

That is the route for diagrams on reference pages: put the image markdown inside a description field in the spec, and the generated page carries it. It also means the diagram line lives in the OpenAPI file under version control, which pairs naturally with regenerating the diagram from the same spec, covered in a living diagram from OpenAPI.

The embed follows the diagram within minutes of an edit; updating the diagram when the API or architecture changes is the remaining loop. Datadef ships an MCP server (registry name io.datadef/mcp), so an agent with access to your repo or spec can update the diagram to match, after a merge, in CI, or on request. Datadef does not watch repositories or specs; regeneration happens when an agent call or CI command asks. API access for agents ships with the paid plans.

Limits, stated plainly: the embed URLs require the source project to be shared public and 404 if it goes private. And Datadef syncs diagrams only. Your endpoint documentation, parameter tables, and prose are ReadMe's domain and your review process's problem, part of the wider practice of keeping API docs in sync with code.

• Embed diagrams in Markdown
• Embed diagrams in GitBook
• Keep API docs in sync with code
• A living diagram from OpenAPI