How to embed uxxu.io architecture diagrams anywhere

How to embed uxxu.io architecture diagrams anywhere

One of the most frustrating things about architecture diagrams is how quickly they become stale. You draw a beautiful C4 Container diagram, export it as a PNG, drop it into your Notion page or your Medium article — and six weeks later the system has changed, the diagram is wrong, and nobody has updated it because the update means re-exporting, re-uploading, and re-linking from scratch.

uxxu.io solves this with live embeds. When you embed a uxxu.io diagram, you are embedding the diagram itself — not a snapshot of it. When the diagram is updated in uxxu.io, every embed updates automatically. The Notion page, the Medium article, the internal docs site — all stay in sync with zero extra effort.

This guide covers every embed method uxxu.io supports, with copy-paste code for each.

---

Getting the embed code

Before embedding anywhere, you need the embed snippet for your diagram.

1. Open the diagram in uxxu.io
2. Click Share in the top right
3. Select Embed / Share
4. Choose your format: HTML, JavaScript, or React
5. Copy the snippet

You will see a data-id attribute in every snippet — for example data-id="mF0ipX8qgYPd67L8kWyy". This ID uniquely identifies your diagram. Every embed method below uses this same ID.

---

Embedding in Notion

Notion supports live embeds via its /embed block. uxxu.io diagrams render as fully interactive, navigable C4 views — not static images.

Step by step

1. In your Notion page, type /embed and select the Embed block
2. In uxxu.io, go to Share → Embed / Share → Copy (the plain link, not the HTML)
3. Paste the uxxu.io share URL into the Notion embed block
4. Press Enter or click Embed link

The diagram renders inline in your Notion page. Viewers can navigate between C4 levels, zoom, and pan — all without leaving Notion.

What updates automatically

When you update the diagram in uxxu.io — add a new container, rename a service, add a deployment node — the Notion embed reflects the change immediately on next load. No re-embedding required.

Tips for Notion embeds

• Resize the embed block by dragging its bottom edge. A height of 500–600px works well for most C4 diagrams.
• Use the Full width toggle in Notion to give the diagram more horizontal space — architecture diagrams benefit from width.
• Add a caption below the embed block naming the diagram level: "Container diagram — production system, April 2026." Notion captions do not update automatically, so keep them at the level of information that changes rarely.

---

Embedding in Medium

Medium supports embeds from a curated list of providers via its embed card. uxxu.io is supported.

Step by step

1. In your Medium draft, paste the uxxu.io share URL on its own line (no other text on that line)
2. Press Enter
3. Medium converts the URL into an embed card automatically

That is it. The diagram renders inline in the Medium post as an interactive embed. Readers can interact with it — navigate between C4 levels, zoom — without leaving Medium.

Notes on Medium embeds

Medium embeds are live — the diagram shown is always the current version in uxxu.io. If you update the architecture after publishing the post, readers see the updated diagram without any action required from you.

Medium's embed cards have a fixed aspect ratio on mobile. On desktop, the embed renders at full width within the Medium content column. For most C4 diagrams, this is sufficient. For particularly wide deployment diagrams, consider using the HTML embed method on your own site for maximum control over dimensions.

---

Embedding with HTML

For any website, internal documentation portal, or CMS that allows raw HTML, the HTML embed gives you full control over dimensions.

The snippet

<div style="width: 1000px; height: 600px;">
  <script
    src="https://app.uxxu.io/embedded/embed.js"
    data-id="mF0ipX8qgYPd67L8kWyy"
  ></script>
</div>

Paste this wherever you want the diagram to appear. The div wrapper controls the dimensions — adjust width and height to fit your layout.

Making it responsive

The fixed-pixel wrapper works for desktop-first documentation sites, but for responsive layouts you want the diagram to flex with the container width:

<div style="width: 100%; height: 600px;">
  <script
    src="https://app.uxxu.io/embedded/embed.js"
    data-id="mF0ipX8qgYPd67L8kWyy"
  ></script>
</div>

Setting width: 100% makes the diagram fill its parent container. The height stays fixed at 600px — adjust this based on your diagram's proportions. For tall deployment diagrams, 700–800px works better. For compact Context diagrams, 400–500px is usually enough.

Multiple diagrams on one page

If you are embedding several diagrams on the same page — for example, all four C4 levels of the same system — use the JavaScript snippet instead of the HTML snippet to avoid loading the embed script multiple times.

---

Embedding with JavaScript

The JavaScript snippet loads the embed script once and renders a diagram wherever the <script> tag appears. This is the right approach when embedding multiple diagrams on the same page.

The snippet

<script
  src="https://app.uxxu.io/embedded/embed.js"
  data-id="mF0ipX8qgYPd67L8kWyy"
></script>

Place this tag inside any container element on your page. The embed script sizes the diagram to fill the container, so wrap it in a div with explicit dimensions:

<div style="width: 100%; height: 600px;">
  <script
    src="https://app.uxxu.io/embedded/embed.js"
    data-id="mF0ipX8qgYPd67L8kWyy"
  ></script>
</div>

Multiple diagrams with one script load

For multiple diagrams on the same page, load the embed script once in your page <head> and use data-id attributes on placeholder elements to identify which diagram to render in each location:

<head>
  <script src="https://app.uxxu.io/embedded/embed.js" async></script>
</head>

<body>
  <h2>System Context</h2>
  <div
    data-uxxu-id="mF0ipX8qgYPd67L8kWyy"
    style="width: 100%; height: 500px;"
  ></div>

  <h2>Container diagram</h2>
  <div
    data-uxxu-id="ANOTHER_DIAGRAM_ID"
    style="width: 100%; height: 600px;"
  ></div>

  <h2>Deployment diagram</h2>
  <div
    data-uxxu-id="YET_ANOTHER_DIAGRAM_ID"
    style="width: 100%; height: 700px;"
  ></div>
</body>

This pattern — one script load, multiple data-uxxu-id containers — is the most performant approach for documentation pages that show the full C4 hierarchy.

---

Embedding in React

For React applications — whether a Next.js documentation site, a Docusaurus instance, a custom internal portal, or a React-based blog — use the React component pattern.

The component

import { useEffect } from "react";

export default function UxxuDiagram({
  id,
  height = 500,
}: {
  id: string;
  height?: number;
}) {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://app.uxxu.io/embedded/embed.js";
    script.async = true;
    script.dataset.id = id;

    const container = document.getElementById(`uxxu-container-${id}`);
    container?.appendChild(script);

    return () => {
      script.remove();
    };
  }, [id]);

  return <div id={`uxxu-container-${id}`} style={{ width: "100%", height }} />;
}

Usage

// Single diagram
<UxxuDiagram id="mF0ipX8qgYPd67L8kWyy" />

// With custom height
<UxxuDiagram id="mF0ipX8qgYPd67L8kWyy" height={700} />

// Multiple diagrams on the same page
<h2>Context diagram</h2>
<UxxuDiagram id="mF0ipX8qgYPd67L8kWyy" height={450} />

<h2>Container diagram</h2>
<UxxuDiagram id="CONTAINER_DIAGRAM_ID" height={600} />

<h2>Deployment diagram</h2>
<UxxuDiagram id="DEPLOYMENT_DIAGRAM_ID" height={750} />

Why the component is structured this way

The useEffect hook appends the embed script to the container div when the component mounts and removes it when it unmounts. This is the correct pattern for dynamically loading third-party scripts in React — it avoids the document.write anti-pattern, works with server-side rendering (the effect only runs on the client), and properly cleans up when the component is removed from the DOM.

The id prop is used to generate a unique container ID (uxxu-container-${id}) — this prevents collisions when multiple UxxuDiagram instances are on the same page.

Next.js usage

The component works in Next.js with the App Router. Because the embed script uses browser APIs, mark the component as a Client Component:

"use client";

import { useEffect } from "react";

export default function UxxuDiagram({
  id,
  height = 500,
}: {
  id: string;
  height?: number;
}) {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://app.uxxu.io/embedded/embed.js";
    script.async = true;
    script.dataset.id = id;

    const container = document.getElementById(`uxxu-container-${id}`);
    container?.appendChild(script);

    return () => {
      script.remove();
    };
  }, [id]);

  return <div id={`uxxu-container-${id}`} style={{ width: "100%", height }} />;
}

Then import it in any Server Component page:

// app/architecture/page.tsx
import UxxuDiagram from "@/components/UxxuDiagram";

export default function ArchitecturePage() {
  return (
    <main>
      <h1>System architecture</h1>
      <p>
        Live C4 diagrams — updated automatically when the architecture changes.
      </p>

      <h2>Context diagram</h2>
      <UxxuDiagram id="mF0ipX8qgYPd67L8kWyy" height={450} />

      <h2>Container diagram</h2>
      <UxxuDiagram id="CONTAINER_DIAGRAM_ID" height={600} />
    </main>
  );
}

---

Embedding in other platforms

Confluence

Confluence supports iframe embeds via the HTML macro. In any Confluence page:

1. Insert a HTML macro (available in Confluence Cloud and Data Center)
2. Paste the HTML snippet inside the macro

<div style="width: 100%; height: 600px;">
  <script
    src="https://app.uxxu.io/embedded/embed.js"
    data-id="mF0ipX8qgYPd67L8kWyy"
  ></script>
</div>

The diagram renders live in the Confluence page and updates automatically when changed in uxxu.io.

Note: Confluence Cloud's HTML macro requires the HTML macro app to be enabled by an administrator. On Confluence Data Center it is available by default.

Slack

Paste the uxxu.io share URL directly into a Slack message. Slack renders a preview card with the diagram title and a link to view the full interactive diagram. Slack does not render interactive embeds inline — it shows a link preview. For interactive viewing, team members click through to uxxu.io.

For persistent architecture references in Slack, pin the uxxu.io share URL in the relevant channel's bookmarks.

Docusaurus

Docusaurus supports MDX — Markdown with embedded JSX. Drop the React component into your docs:

import UxxuDiagram from "@site/src/components/UxxuDiagram";

# System architecture

The following diagram shows the Container-level view of the production system.

<UxxuDiagram id="mF0ipX8qgYPd67L8kWyy" height={600} />

All containers and their relationships are described in detail below.

This makes uxxu.io diagrams first-class citizens in your Docusaurus documentation site — live, interactive, and always in sync with the current architecture.

GitBook

GitBook supports embeds via its /embed block. Paste the uxxu.io share URL into a GitBook embed block — the same way as Notion. The diagram renders as an interactive embed within the GitBook page.

---

When to use each method

Platform	Method	Live updates	Interactive
Notion	Embed block (paste URL)	Yes	Yes
Medium	Paste URL on its own line	Yes	Yes
Confluence	HTML macro	Yes	Yes
React / Next.js	UxxuDiagram component	Yes	Yes
Plain website	HTML snippet	Yes	Yes
Docusaurus	MDX + React component	Yes	Yes
GitBook	Embed block	Yes	Yes
Slack	Paste URL (link preview)	No	No (click-through)

---

Why live embeds matter for architecture documentation

Most architecture documentation fails not because it was never created, but because it was created once and never updated. Teams export a PNG, paste it into their documentation, and move on. The system evolves; the diagram does not. Within a few months, the documentation is misleading at best and actively harmful at worst — it gives readers confidence in a model of the system that no longer exists.

Live embeds change this dynamic. The diagram in your Notion page, your Medium article, your internal docs site — it is the diagram, not a copy of the diagram. When an engineer adds a new container in uxxu.io after a service extraction, the Notion page reflects the change on next load. There is nothing to re-export, re-upload, or re-link.

This is the same reason the best codebases are the ones where the tests live next to the code they test, not in a separate repository. Proximity eliminates the friction that causes drift. Live embeds eliminate the friction that causes architecture documentation to go stale.

---

Frequently asked questions

Does changing the diagram in uxxu.io break existing embeds?

No. The embed is identified by the diagram ID in the data-id attribute. As long as the diagram exists in uxxu.io, all embeds pointing to that ID will continue to render the current version of the diagram.

Can viewers edit the diagram through an embed?

No. Embeds are view-only. Viewers can navigate between C4 levels, zoom, and pan, but they cannot make changes to the underlying diagram. Editing requires opening the diagram directly in uxxu.io with an account that has edit access.

Does the embed work if the viewer does not have a uxxu.io account?

Yes. Embeds are publicly accessible for any diagram that has sharing enabled. Viewers do not need a uxxu.io account to see an embedded diagram.

What happens if the embed script is blocked by a content security policy?

If your website has a strict Content Security Policy (CSP), you may need to add app.uxxu.io to your script-src and frame-src directives. The embed script loads from https://app.uxxu.io/embedded/embed.js — add this origin to your CSP allowlist.

Can I embed a specific C4 level rather than the full interactive diagram?

By default, the embed shows the full interactive diagram with navigation between levels. To embed a specific level view, generate the embed link from that specific view in uxxu.io — the data-id for a specific view will show only that level.

---

Summary

Embedding uxxu.io diagrams is straightforward across every platform:

• Notion and GitBook — paste the share URL into an embed block
• Medium — paste the share URL on its own line in a draft
• Confluence — use the HTML macro with the HTML snippet
• Plain HTML — wrap the <script> tag in a sized <div>
• React / Next.js — use the UxxuDiagram component with useEffect
• Docusaurus — use the React component in MDX files

In every case, the embed is live — viewers always see the current state of the diagram, and you never need to re-export or re-upload when the architecture changes.

Open uxxu.io and create your first embeddable diagram →

---

Which embed option should you choose?

The best embed method depends on where the diagram needs to live.

• Use Notion when the goal is internal documentation, project spaces, or architecture notes that non-engineers also read.
• Use Medium when the goal is public writing, thought leadership, or product marketing with live architecture examples.
• Use HTML when you want the simplest website integration with direct control over width and height.
• Use JavaScript when you need several diagrams on one page and want to avoid loading the embed script repeatedly.
• Use React when the diagram is part of a modern product, docs site, portal, or internal tool built with components.

That choice matters because the technical integration is only part of the story.

You are also choosing where architecture knowledge will be consumed. A diagram inside Notion supports internal collaboration. A diagram inside Medium supports external education. A diagram inside your own product or docs site makes architecture part of the user experience itself.

---

More embedding questions

Which embed method is best for documentation teams?

For most documentation teams, Notion or HTML is the easiest place to start. Notion works well for internal docs and lightweight publishing. HTML works well for owned websites and portals where you want direct control over layout.

Do embedded uxxu.io diagrams update automatically?

Yes. Uxxu embeds are live, not static screenshots. When the source diagram changes in uxxu.io, the embedded version reflects that update the next time the page loads.

Can I embed several diagrams on one page?

Yes. If you are embedding several diagrams on the same page, the JavaScript or React patterns are usually the cleanest choices. They make it easier to manage sizing and performance across multiple views.

Why is embedding better than using screenshots?

Because screenshots go stale quickly. Embeds keep the architecture current, interactive, and easier to navigate. That means the diagram in the docs stays aligned with the actual diagram in your workspace instead of becoming another outdated asset to maintain manually.

---