Embed Sequence Diagrams in Your Website: WordPress, Blogs, and Documentation

Embedding a sequence diagram on your website or blog gives readers visual documentation without requiring them to leave the page. The three approaches (static SVG, Mermaid via CDN, iframe embed) each have tradeoffs. For most blogs and documentation sites, a simple SVG export gives the best performance and reliability.

Create your diagram in our free sequence diagram tool, export as SVG, and embed. No API key, no account, no rate limits on visitors viewing your embedded diagrams.

Method 1: Static SVG File (Simplest, Fastest)

Export your diagram as SVG from our tool, upload to your site, reference like any other image. This is the most reliable method because it has no runtime dependencies.

WordPress workflow:

1. Create your diagram and export as SVG
2. Upload via Media Library (WordPress 5.0+ supports SVG with proper configuration)
3. Insert as image in your post

If your WordPress blocks SVG uploads (some configurations do for security reasons), install the Safe SVG plugin or export as PNG instead.

For static site generators (Jekyll, Hugo, Next.js, Gatsby):

![API Auth Flow](/images/auth-flow.svg)

Or with HTML for more control:

<img src="/images/auth-flow.svg" alt="Auth sequence diagram" width="600" loading="lazy">

Advantages: smallest page weight, renders instantly, works without JavaScript, searchable by screen readers when you include alt text.

Disadvantages: static only. If you update the diagram, you re-export and re-upload. Readers cannot zoom or interact with it.

Method 2: Mermaid via CDN (Interactive)

For blog platforms that support custom HTML/JavaScript, you can embed the Mermaid library and write your diagram source directly in the page. The library renders it in the browser.

<script src="https://cdn.CDN/npm/mermaid@10/dist/mermaid.min.js"></script>
<div class="mermaid">
sequenceDiagram
    actor User
    participant API
    User->>API: Request
    API-->>User: Response
</div>
<script>mermaid.initialize({startOnLoad: true});</script>

Advantages: the diagram source is in the page (editable), readers can technically view-source to see the Mermaid code, the diagram scales responsively.

Disadvantages: requires JavaScript (readers with JS disabled see nothing), adds ~100KB of Mermaid library load, the library has to parse and render on every page view.

Best for: documentation sites where readers are developers who will appreciate the source being visible. For general blog posts, SVG is usually better.

Sell Custom Apparel — We Handle Printing & Free Shipping

Method 3: Iframe Embed (Rare Use Cases)

Iframe embedding is uncommon for sequence diagrams but works if you have a hosted Mermaid editor or diagram viewer:

<iframe src="https://your-diagram-viewer.com/embed/abc123"
        width="600" height="400"
        frameborder="0"></iframe>

This approach works when you are using a hosted diagram service that provides shareable URLs. The downside: you depend on that external service remaining available. If the service goes down or changes policies, your embedded diagrams break.

For most cases, SVG export gives you permanent, self-hosted diagrams with no external dependencies. Iframe embedding is useful mainly for collaborative diagrams that multiple people edit, where you want the embed to always show the latest version.

Platform-Specific Embed Tips

WordPress: Use SVG with the Safe SVG plugin for security. Or use a Mermaid plugin (several exist, free) that lets you write Mermaid code in shortcodes. Example: [mermaid]sequenceDiagram ... [/mermaid] renders as a diagram.

Ghost: Ghost has built-in support for Mermaid in its code blocks. Write a code block with "mermaid" as the language and it renders automatically.

Medium: Medium does not support custom HTML, JavaScript, or SVG uploads. You are limited to PNG exports uploaded as images. This is a significant limitation for technical writers.

Substack: Similar to Medium. Upload PNG exports as images. No native Mermaid or SVG support.

Notion (as embedded blog): Native Mermaid support. Type /mermaid and paste your code.

Static site generators: Jekyll and Hugo have Mermaid plugins. Next.js and Gatsby can integrate Mermaid via React components. For maximum portability, export SVG and treat as images; the diagrams work in any framework.

For documentation-focused sites, see our GitHub native rendering guide — GitHub Pages sites render Mermaid directly.

Making Embedded Diagrams Accessible and SEO-Friendly

Diagrams are visual and don't provide text content that search engines can index. Without proper markup, they are invisible to SEO and unusable for screen reader users. Fix both with:

• Meaningful alt text. Describe what the diagram shows: "Sequence diagram showing user authentication flow with JWT token exchange" beats "auth diagram"
• Surrounding text. Reference the diagram in the body of your post. Explain what the diagram demonstrates. This gives search engines and readers context.
• Text alternative below the image. For complex diagrams, include a text summary of the flow. "The user submits credentials, the auth service verifies them, and on success returns a JWT that the app stores."
• Semantic HTML. Wrap diagrams in <figure> with <figcaption> for proper semantic structure

For blog posts specifically, the combination of a well-alt-texted diagram plus descriptive body text gives you the visual appeal of the diagram plus the searchable text content that drives SEO.

Frequently Asked Questions

How do I embed a sequence diagram in WordPress?

The simplest method: export your diagram as SVG from our tool, upload via WordPress Media Library (requires Safe SVG plugin for security), and insert as an image in your post. Alternative: install a Mermaid plugin that renders Mermaid code via shortcodes.

Can I embed an interactive sequence diagram in my blog?

Yes, using the Mermaid CDN method. Include the Mermaid script in your page and write the diagram source inside a div with class mermaid. The library renders it client-side. Works in blog platforms that allow custom HTML and JavaScript.

Do I need an API key to embed sequence diagrams?

No. Our tool exports SVG files directly. No API key, no usage limits, no rate limiting on your visitors. The SVG is yours to use forever. The same applies to Mermaid CDN embedding — no authentication, no account, no quotas.

What is the best format for embedded sequence diagrams: SVG or PNG?

SVG for almost every case. It scales to any size without blur, files are usually smaller than equivalent PNG, and accessibility tools can interact with SVG elements. Use PNG only when your platform does not support SVG (Medium, Substack, older email clients).