Content Display

When a Confluence visitor views a page containing an HTML macro, the content is rendered inside a secure sandboxed iframe. This page explains how that rendering works.

Rendering Pipeline

  1. The saved HTML, CSS, and JavaScript are loaded from the macro configuration
  2. The content is sanitised according to the active security settings
  3. A Content Security Policy (CSP) header is injected into the iframe
  4. The iframe renders the content — visitors see the final output

This two-layer approach (regex sanitisation + browser-enforced CSP) means external resources are blocked at both the content level and the network level.

iframe Sandbox

The content runs inside a sandboxed <iframe> with the following permissions:

Permission Status Purpose
allow-scripts ✅ Enabled Run JavaScript
allow-same-origin ✅ Enabled Access browser APIs
allow-modals ✅ Enabled Use alert(), confirm()
allow-popups ✅ Enabled Open new windows (relayed via Forge)
allow-forms ✅ Enabled Submit forms

Automatic Height

The macro automatically adjusts its height to match the content inside. There is no fixed height — the iframe expands to fit your content exactly, with no unnecessary whitespace.

If your HTML sets an explicit height on the <body> or a container element, that height is respected and the content scrolls internally within that constraint.

All links and window.open() calls inside your macro are intercepted and routed through Confluence's navigation system:

  • target="_blank" links — open in a new browser tab via Confluence's router
  • Regular links — navigate within Confluence
  • window.open(url) — handled identically to target="_blank"

This is necessary because Forge apps cannot open URLs directly — all navigation goes through the Atlassian bridge.

Blocked Content Placeholders

When a resource is blocked by the Content Security Policy, the macro shows a friendly placeholder instead of the browser's broken-resource icon:

Block-all mode:

🔒 Content Blocked This content is blocked by your administrator's security policy.

Whitelist mode (domain not listed):

🔒 Content Blocked This domain isn't whitelisted. Contact your site administrator to allow it.

Content Size Limit

If the total content (HTML + CSS + JS) exceeds the maximum size configured by your admin, the macro displays an error page instead of rendering:

Content Size Exceeded Content size exceeds the maximum allowed limit of X KB.

Contact your admin to increase the limit, or reduce the size of your macro content.

Security Modes Summary

Mode External resources Behaviour
Block all ❌ All blocked No external images, iframes, scripts, or styles load
Whitelist only ✅ Listed domains only Only resources from whitelisted domains load
Allow all ✅ All allowed All external resources load (not recommended for production)

See Security Settings for configuration details.