.png&w=64&q=75){kind=small}
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
- The saved HTML, CSS, and JavaScript are loaded from the macro configuration
- The content is sanitised according to the active security settings
- A Content Security Policy (CSP) header is injected into the iframe
- 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.
Link Handling
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 totarget="_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.