TL;DR: Add one script tag to your page, then use `` or inline your IaC code between the tags. The diagram renders interactively, updates when you update the source, and never sends your code to a server.

Why living diagrams beat static images in docs

There's a specific kind of documentation rot that hits infrastructure teams hard: the architecture diagram that was accurate when someone drew it, is now pinned to a Confluence page, and describes an environment that no longer exists. Someone added an RDS read replica. Someone else swapped EC2 for ECS Fargate. The diagram stayed put.

Static diagram images — PNGs and SVGs exported from draw.io or Lucidchart — have a structural problem. Keeping them current requires someone to remember to update them, have the original tool open, export a new image, and re-upload it. That chain breaks constantly in practice. Not because people are careless; they're just busy.

A living diagram solves this by rendering from the actual IaC file every time the page loads. When the Terraform changes, the diagram changes. No export, no re-upload, no manual step. It's accurate because it's always generated from the current code, not from a snapshot.

The InfraSketch embed component makes this work on any website, docs platform, or wiki that accepts custom HTML: one script tag, then drop the `` element wherever you want the diagram.

Two ways to embed: iframe vs web component

Two ways to embed, and which one you use depends on your platform:

The iframe approach works everywhere — Confluence, Notion, GitHub Pages, internal wikis, anything that allows an HTML iframe. You generate a diagram URL first (browser tool, CLI, or MCP server), then paste the iframe tag. It's a bit more manual but totally reliable across any platform, including those that restrict JavaScript.

The web component is cleaner for HTML-based sites. One script tag in the head, then use `` anywhere on your page — point it at a source URL or write IaC code inline between the tags. The component fetches, detects the format, and renders. For docs sites built with MkDocs, Docusaurus, Hugo, or Jekyll, this is the approach I'd recommend.

Getting the iframe embed code (from the app)

If you have an existing diagram open in the InfraSketch web app, the fastest way to get embed code is the share button. The app generates both an iframe snippet and a direct link:

`plaintext

`

Paste this into any HTML page or any platform with an HTML/embed block. The iframe is fully self-contained — the diagram state is in the URL, so there are no external dependencies beyond the InfraSketch web app itself.

For platforms that strip the src attribute from iframes for security reasons (some wiki platforms and CMS editors do this), see the CORS considerations section below.

The infra-sketch web component: one-line setup

The web component is loaded with a single script tag that you add once to your page's or just before :

`plaintext

`

After loading, the `` custom element is registered and available anywhere on the page. It renders as a responsive iframe-like widget with pan and zoom support, the same interactive experience as the full web app.

The script is small, loads from a CDN, and is cached aggressively. Including it on a documentation page adds negligible overhead — the component only fetches and renders when an `` element is actually present in the DOM, so unused script inclusions don't trigger any work.

Embedding by URL: the src= attribute

The simplest way to embed a diagram is to point the component at a URL that returns IaC code. The component fetches the URL, detects the format, and renders the diagram:

`plaintext

`

When the page loads, the component fetches the src URL, reads the content, auto-detects the IaC format, and renders the interactive diagram. If the file changes in GitHub, the diagram on your documentation page changes the next time someone loads it — without any manual intervention.

You can also pass an explicit type attribute to skip format detection and ensure correct rendering for ambiguous files:

`plaintext

`

The height attribute sets the diagram height in pixels. If omitted, a default of 480px is used. Width is always 100% of the container element, making the component responsive to its parent layout.

Embedding inline code

For documentation where you want to show a specific, curated snippet rather than an entire file, write the IaC code directly between the `` tags:

apiVersion: apps/v1
kind: Deployment
metadata:
name: api-server
namespace: production
spec:
replicas: 3
selector:
matchLabels:
app: api-server
template:
spec:
containers:
- name: api
image: your-org/api:latest
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: api-service
spec:
selector:
app: api-server
ports:
- port: 80
targetPort: 8080
type: ClusterIP

When no src attribute is provided, the component uses the element's text content as the IaC code. The type attribute is recommended for inline code since there's no file extension to auto-detect from. The content is treated as plain text — HTML entities inside the element are decoded before parsing, so you can use `
Tip: For documentation sites that process Markdown, wrap inline IaC code in a raw HTML block to prevent the Markdown parser from mangling the whitespace or escaping characters inside the element.

All supported attributes (src, type, height, width)

The component also exposes a custom event, infra-sketch-load, that fires when the diagram has finished rendering. You can listen to it for analytics, lazy-load triggers, or to show/hide a loading skeleton:

javascript
document.querySelector('infra-sketch').addEventListener('infra-sketch-load', (e) => {
console.log('Diagram rendered:', e.detail.resourceCount, 'resources');
});


Real examples: GitHub Pages docs, Backstage, Confluence, Notion

GitHub Pages / Jekyll / Hugo / MkDocs

For static site generators, add the embed script to your theme's base template and use the component in any page. For MkDocs with the Material theme, add the script to overrides/main.html. For Jekyll, add it to _layouts/default.html. Then use the component in any Markdown file within a raw HTML block:

`markdown

Network Architecture

The following diagram shows the production VPC layout:

`

Backstage TechDocs

Backstage TechDocs is built on MkDocs and renders Markdown for service catalogs. The same pattern applies — add the script to the TechDocs theme override and embed diagrams inline in your service's docs/ directory. Because TechDocs serves content from the same origin as Backstage, there are no CORS restrictions when fetching from GitHub raw URLs.

Confluence

Confluence's HTML macro lets you paste raw HTML including script tags. Create an HTML macro block on your page, paste in the embed script tag and the element. Alternatively, use the iframe approach — generate the iframe URL from the InfraSketch app and paste it using Confluence's iframe macro. The iframe approach is more reliable across Confluence versions since some restrict JavaScript in HTML macros by default.

Notion

Notion doesn't support arbitrary HTML or script tags in pages, but it does have an Embed block that accepts iframe URLs. Generate the diagram URL from the InfraSketch app (or via the CLI with --no-open), then use Notion's /embed command and paste the URL. Notion will render it as an embedded iframe. The result is an interactive diagram inside your Notion page that anyone with page access can pan and zoom.

Loading from GitHub raw URLs — the recommended pattern

Pointing the src attribute at a GitHub raw URL is the most maintainable pattern for living diagrams. The URL format is:

plaintext
https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}


For example:

`plaintext

`

When main.tf is updated and merged, the next page load will show the updated diagram. No documentation update required. No diagram export needed. The diagram is always synchronized with the code in your default branch.

For branch-specific documentation — for example, showing the architecture as it will look after a specific feature branch is merged — use the branch name in the URL:

`plaintext

`

This is particularly useful when combined with the GitHub Action, which posts a diagram to the PR. You can also link to branch-specific documentation that shows what the architecture will look like after the PR is merged, and the diagram will automatically become the "post-merge" diagram once the branch is merged to main.

For private repositories, GitHub raw URLs require authentication. In that case, you can either use the inline code approach (copy the relevant code into your documentation page directly) or host your own IaC files on an authenticated endpoint and point src at that.

Error handling and CORS considerations

When using the src attribute, the web component fetches the URL from the browser using the Fetch API. This means the target URL must be accessible from the user's browser and must allow cross-origin requests via CORS headers.

GitHub raw URLs (raw.githubusercontent.com) are served with permissive CORS headers — they allow requests from any origin, so they work out of the box. Most public file hosting services and CDNs also support CORS for public content.

If the src URL is on a private server or an origin that doesn't send CORS headers, the fetch will fail with a network error. In that case:

• Use inline content instead of src
• Configure your server to send Access-Control-Allow-Origin: * for the IaC files
• Use a CORS proxy (only for non-sensitive content)
• Generate the diagram URL server-side and embed it as a static iframe URL instead of using the web component's dynamic fetch

When a fetch fails, the component shows a visible error state — it doesn't silently disappear. Non-200 response, empty body, network error — you get "Could not load diagram source" in the widget and the actual error in the browser console, so you know what went wrong.

For inline content, there's no network request and no CORS consideration — the content is right there in the DOM, and the component reads it synchronously.

Privacy: what the embed does and doesn't send

Same privacy model as the rest of InfraSketch: your IaC code never touches InfraSketch servers. Here's exactly what happens when you use src:

1. The browser fetches the src URL — request goes to GitHub or wherever you're hosting the file, not to InfraSketch
2. File content lands in the browser
3. The component encodes it into a URL fragment (gzip + base64) in-memory
4. Creates an iframe pointing to https://infrasketch.cloud/#
5. Browser loads the InfraSketch web app — the HTTP request goes to our CDN, but fragments are never included in HTTP requests (that's the HTTP spec)
6. The web app decodes the fragment client-side and renders

What InfraSketch servers actually see: a request for the embed script, a request for the web app assets. That's it. No IaC code, no diagram content, no infrastructure metadata. Standard CDN logs with IP, user agent, timestamp — same as any website.

With inline content, step 1 doesn't happen at all. The only network contact is loading the web app assets.

A complete minimal embed page

Here's a full, self-contained HTML page that embeds a Terraform diagram using the web component. You can use this as a starting point for a GitHub Pages documentation page or any static HTML site:

`css

Network Architecture - Internal Docs

body { font-family: system-ui, sans-serif; max-width: 900px; margin: 40px auto; padding: 0 20px; }
h1 { font-size: 24px; margin-bottom: 8px; }
p { color: #555; margin-bottom: 24px; }

Production Network Architecture
This diagram is generated live from the Terraform source in the infra repository.

Diagram always reflects the current main branch. View source

`

This page requires no build step, no server-side processing, and no InfraSketch account. It works as a standalone HTML file served from any static host.

FAQ

Does the embed component work with private GitHub repositories?

The src fetch runs in the user's browser, so private GitHub raw URLs would need a token — which you obviously can't bake into a public HTML page. For private repos, use inline content instead: copy the relevant Terraform or Kubernetes code between the tags. Or generate the URL server-side with npx infrasketch main.tf --no-open and embed it as a static iframe. The state is in the fragment, so it doesn't expire.

Will the diagram break if infrasketch.cloud goes down?

If the web app is unavailable, iframes and components pointing to it will show an error. If you need high reliability for critical docs, pre-generate the URL with the CLI and embed it as a static iframe — then if you ever want to self-host the web app, the same URL works unchanged.

Can I control the diagram layout or colors through the embed?

Not through attributes currently. Users can pan, zoom, and move nodes interactively inside the embedded diagram. If you want a specific layout, open the diagram in the full web app, arrange it, and use the "share" URL — it encodes the adjusted node positions in the fragment. Custom theming via attributes is on the roadmap.

Does the component support lazy loading for pages with many diagrams?

Yes — it uses IntersectionObserver internally to defer fetching and rendering until the element is near the viewport. Put 10 diagrams on a page and only the visible ones actually load. The rest wait until you scroll to them. This makes diagram-heavy runbooks and wikis load fast enough to be practical.

Can I use the embed component with React, Vue, or other frameworks?

Web components work natively in all modern browsers, so any framework is fine. React treats it like any other HTML element. Vue might show an "unknown element" warning — add infra-sketch to compilerOptions.isCustomElement in your Vite/Vue config to silence it. No npm package needed — just the script tag.

Turn your IaC docs into living architecture diagrams Add one script tag to your docs site and your diagrams stay synchronized with your code automatically. Try it in the browser first — no account needed. Try InfraSketch Free →