Embedwell documentation (source for the EMBDOCS knowledge base)
Getting started
- Edit a page, type
/htmland choose HTML embed (Embedwell). - Write HTML, CSS and JavaScript in their tabs. The preview on the right runs in the same sandbox readers get.
- Tick Run JavaScript if your code needs it (and forms or dialogs if your admin allows them). Choose Fit content or a fixed height.
- Press Save. Saving approves this exact content.
What the sandbox allows and blocks
| Works | Does not work (by design) |
|---|---|
HTML, inline CSS and <style>, SVG, canvas, inline <script> and event handlers (when scripts are granted) | Loading anything from the internet: CDN scripts, stylesheets, web fonts, images, iframes |
Images, fonts, CSS and JS attached to the page, via attachment:name | fetch, XHR, WebSocket, EventSource, workers |
localStorage and sessionStorage (in memory until reload) | Cookies, IndexedDB, persistent storage |
| Links (open through Confluence's leaving-site prompt) | Opening pop-ups, navigating the Confluence page |
alert/confirm/prompt if the admin allows dialogs | eval and new Function |
| Forms with JavaScript submit handlers if the admin allows forms | Submitting a form to a URL |
The browser enforces these rules, so they hold even for code nobody reviewed. To show an external website, use Confluence's built-in iFrame macro.
Approvals and "Scripts are off"
An embed only runs scripts, forms and dialogs if it was saved in the Embedwell editor by someone your admin allows. If the content was pasted from another page by someone outside the allowed groups, changed through the REST API, or an admin reset approvals, readers see the content with scripts off and a short note. Fix: an allowed editor opens the embed and presses Save.
Page attachments
- HTML file as the source: choose Page attachment and pick an
.htmlfile attached to the page. Readers always get the version you saved, even after a newer upload. The editor offers "Use version N" when a newer one exists. - Files inside your HTML:
<img src="attachment:chart.png">,url(attachment:font.woff2),<link rel="stylesheet" href="attachment:site.css">,<script src="attachment:app.js"></script>. Each is pinned to its current version when you save. - Limits: 2 MB per file, 6 MB per embed.
Admin settings (Settings > Embedwell HTML embeds)
- Who can insert and edit embeds: everyone who can edit the page, or members of chosen groups (Confluence admins always can).
- JavaScript: on or off for the site; all spaces, only listed spaces, or all except listed.
- Forms, dialogs, attachments, tallest auto-height embed.
- External resources: always blocked (Runs on Atlassian).
- Reset approvals: replaces the signing key; every embed runs with scripts off until an allowed editor saves it again.
- Activity: the last 300 saves and settings changes.
Limits
- Inline source: 120 KB (HTML + CSS + JS). Larger: attach the file.
- Auto-height: up to the admin cap (default 4,000 px), then the embed scrolls.
- PDF and Word exports show the embed's text in a panel; scripts do not run in exports.
Troubleshooting
- The preview lists "Blocked a script from https://...": download the library and attach it.
- "Line N: ..." under the preview: a JavaScript error in your code at that line.
- Characters look wrong / tags shown as text: use Fix encoding when the editor offers it.
Open-source licenses
React and React DOM (MIT). @forge/bridge, @forge/resolver, @forge/api, @forge/kvs (Atlassian, Apache 2.0 / MIT as published).