Embed diagrams in Nextra: plain img, next/image, and the MDX rules between them

A Markdown image or a lowercase img tag pointed at an external URL renders with zero configuration: the browser fetches the image straight from the source. The next/image component is stricter: any external host must be listed under images.remotePatterns in next.config, and unlisted hosts throw at request time.

For a live diagram, the plain form is not just simpler, it is more correct. next/image routes the file through the Next.js optimizer, which serves a cached, transformed copy from your own server, adding a second cache between the reader and the source. A plain img keeps the fetch direct, so Datadef's cache headers apply as designed: the image carries an ETag from the diagram's last edit and a five minute cache lifetime, and an edited diagram shows up on the page within minutes. Save next/image for local screenshots where build-time optimization and blur placeholders actually pay off.

Nextra pages are MDX, and MDX bodies are compiled as JSX, not HTML. Pasted embed code fails on three predictable rules. First, style attributes must be objects: style="width:100%" is a compile error, style={{ width: "100%" }} is correct. Second, every tag must be closed or self-closed; an unclosed iframe fails the compile. Third, HTML comments are not valid in MDX bodies; use JSX comments instead.

Within those rules, an iframe works directly in any MDX page, no plugin or component wrapper needed. That gives readers a pannable, zoomable diagram instead of a fixed image.

{/* Live image: no config needed for a plain img or Markdown image */}
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4)

{/* Interactive embed: JSX rules apply, note the style object and closed tag */}
<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  style={{ width: '100%', height: 480, border: 'none' }}
  title="Platform architecture"
/>

If you do want next/image for the diagram, allowlist the host once. And if your docs deploy as a static site with output: "export", remember the default image optimizer needs a server: either set images.unoptimized to true or supply a custom loader. Plain img tags are unaffected by static export, which is one more reason they are the default choice for external diagrams.

// next.config.mjs
export default {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'datadef.io', pathname: '/api/embed/**' },
    ],
    // required if you combine next/image with output: 'export'
    unoptimized: true,
  },
};

Nextra orders the sidebar from the _meta file in each docs folder, not from the filesystem. An architecture page nobody can find goes stale in a different way: it stops being read, so nobody notices when it is wrong. Add the page to _meta with an explicit position near the top of its section, so the diagram stays on the paths people actually walk.

The embed keeps the page current with the diagram; the diagram still has to be kept current with the code, and that loop can live in the same repository as the Nextra site. A coding agent connected to Datadef over MCP, registry name io.datadef/mcp, can read what a merge changed and update the diagram to match, in CI or on request during review. Datadef itself never watches the repository; the update is a single agent invocation, the granularity a Next.js team already automates everywhere else. Agents authenticate with an API key, a paid-plan feature.

For service-heavy systems where this matters most, see keeping microservices docs in sync.

The embed URLs exist only for projects shared public; flip the project private and the image 404s while the interactive page disappears with it. Confidential architectures should use a committed static export instead and accept the staleness.

Nextra also renders Mermaid in fenced blocks, and for a small flow that lives next to its prose, Mermaid in the same commit is the honest winner. It struggles past roughly twenty nodes or when zones and column detail matter, which is where the embedded form earns its place. The plain Markdown baseline is covered in embed diagrams in Markdown.

• Embed diagrams in Markdown
• Embed diagrams in Docusaurus
• Embed diagrams in VitePress
• Keeping microservices docs in sync