Embedding Diagrams

Embed interactive Archyl diagrams in your documentation platforms, wikis, and collaboration tools.

Supported Platforms

Archyl supports embedding in popular collaboration tools:

Creating an Embed

Step 1: Create a Share Link

1. Open your project
2. Click Share in the toolbar
3. Click Create New Share Link
4. Configure options:
   • Name (e.g., "Confluence Embed")
   • Expiration (optional)
5. Copy the generated link

Step 2: Get Embed Code

1. In the Share dialog, click Embed tab
2. Select your target platform
3. Copy the provided code

Platform-Specific Instructions

Confluence

Using Iframe Macro:

1. Edit your Confluence page
2. Insert the iframe or HTML macro
3. Paste the embed code:

<iframe
  src="https://app.archyl.com/embed/{shareToken}"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

Using Widget Connector:

1. Insert Widget Connector macro
2. Paste the share URL directly
3. Adjust width and height

Notion

1. On a Notion page, type /embed
2. Select Embed
3. Paste your share URL
4. Click Embed link
5. Resize the embed as needed

Miro

1. Open your Miro board
2. Click the Apps icon
3. Search for Embed or iFrame
4. Add the app to your board
5. Paste the share URL
6. Position and resize

SharePoint

1. Edit your SharePoint page
2. Add Embed web part
3. Paste the embed code
4. Save the page

PowerPoint

1. Install Web Viewer add-in
2. Insert the add-in on a slide
3. Enter the share URL
4. Note: Limited interactivity in slideshow mode

Generic Website

Add this HTML to any webpage:

<iframe
  src="https://app.archyl.com/embed/{shareToken}"
  width="100%"
  height="600"
  style="border: none; border-radius: 8px;"
  allowfullscreen
></iframe>

Embedded View Features

The embedded view provides:

Minimal Header

• Project name
• Current C4 level
• Breadcrumb navigation
• Powered by Archyl badge

Full Interactivity

• Pan and zoom the diagram
• Double-click to drill down
• Navigate through all C4 levels
• View element details

Responsive Layout

• Adapts to any container size
• Works in narrow sidebars
• Scales on mobile devices
• Clean, distraction-free design

Customization Options

Size

Adjust width and height in the embed code:

<iframe
  src="..."
  width="800"
  height="600"
></iframe>

Or use percentages:

<iframe
  src="..."
  width="100%"
  height="80vh"
></iframe>

Initial View

Append parameters to control the initial view:

?level=container    # Start at Container level
?level=component    # Start at Component level

Styling

Add custom styles to the container:

<div style="border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;">
  <iframe src="..." width="100%" height="600" frameborder="0"></iframe>
</div>

Best Practices

Keep Links Updated

• Update share links when architecture changes
• Set reasonable expiration dates
• Create separate links for different contexts

Optimize for Viewers

• Start at the appropriate C4 level for your audience
• Executive summary: System Context
• Technical overview: Container
• Implementation details: Component

Document the Embed

Add context around your embedded diagram:

• Brief description of what's shown
• When the diagram was last updated
• Link to full Archyl project for editors

Handle Expired Links

If a share link expires:

1. Create a new share link
2. Update the embed code
3. Inform stakeholders if needed

Troubleshooting

Embed Not Loading

• Check the share link hasn't expired
• Verify the URL is correct
• Check for Content Security Policy restrictions
• Try in an incognito window

Interactivity Issues

• Some platforms restrict iframe interactions
• PowerPoint has limited support during presentations
• Check platform-specific limitations

Size Problems

• Use viewport units (vh, vw) for responsive sizing
• Set minimum height (500px recommended)
• Test on different screen sizes

Next Steps

• Sharing - Create and manage share links
• Export - Export static images
• User Flows - Embed flow visualizations