Embedding Diagrams

Share your diagrams anywhere with native embedding support for GitHub, Notion, Linear, and more.

Quick Start

Every public diagram has an embed URL:

https://illustrate.md/api/embed/{diagram-id}

Just paste this URL in any supported platform, and it will automatically render as an image!

Supported Platforms

GitHub

Works in README.md files, issues, pull requests, and wikis.

![Diagram](https://illustrate.md/api/embed/abc123)

Notion

Use the /embed command or paste the URL directly.

/embed https://illustrate.md/api/embed/abc123

Linear

Paste in issue descriptions and comments for inline rendering.

![Diagram](https://illustrate.md/api/embed/abc123)

Direct Links

Share the URL directly for an interactive preview page.

https://illustrate.md/api/embed/abc123

Customization

Add query parameters to customize the appearance:

Theme

?theme=dark

Size

?width=800&height=600

Font Size & Padding

?fontSize=16&padding=20

Custom Colors

?bg=%23ffffff&fg=%23000000

Privacy & Access

Public Diagrams Only

Only public diagrams can be embedded externally. Make your diagram public before sharing the embed URL. Private diagrams will show "Access Denied" to other users.

Test Your Embeds

Use the embed preview page to test how your diagram will appear on different platforms:

/diagram/{id}/embed

Examples

GitHub README

# My Project

Architecture overview:

![Architecture](https://illustrate.md/api/embed/abc123)

## Components

![Component Diagram](https://illustrate.md/api/embed/def456?theme=dark)

Notion Page

System Design

/embed https://illustrate.md/api/embed/abc123

The diagram above shows our microservices architecture...

Linear Issue

## Implementation Plan

Current state:
![Current](https://illustrate.md/api/embed/abc123?width=600)

Proposed changes:
![Proposed](https://illustrate.md/api/embed/def456?width=600)

Frequently Asked Questions

Why isn't my embed showing?

Make sure your diagram is public. Private diagrams require authentication and won't display for other users.

How long does caching last?

Embeds are cached for 1-24 hours depending on the platform. Updates to your diagram will appear after the cache expires. You can force a refresh by adding a version parameter: ?v=2

Can I embed in other platforms?

The embed endpoint works anywhere that displays images from URLs. If you need support for a specific platform, let us know!

Is there a rate limit?

Embeds are cached aggressively, so there's no practical rate limit for viewing. The endpoint is designed to handle high traffic.