Use AI Assistants to Generate Confluence-Compatible Code with HTML Macro

[#1]

The problem

Confluence's sandboxing means HTML, CSS, and JavaScript that works fine in a regular browser often breaks when pasted into a macro editor. Scripts get stripped, styles clash with the page theme, or elements just don't render. If you're using ChatGPT, Claude, or another AI assistant to write that code, the assistant has no way of knowing about those constraints unless you tell it.

This article walks through a prompt structure that gives your AI assistant the context it needs, so the code it generates works in HTML Macro on the first try (or close to it).

The prompt structure

Paste this into your AI assistant before describing what you want to build:

I'm writing HTML, CSS, and JavaScript to run inside the HTML Macro app
for Atlassian Confluence Cloud. Please follow these constraints:

1. Output a single self-contained block: inline <style> and <script>
   tags, no external file references, no build step.
2. Don't rely on browser APIs that require top-level document access
   (e.g., document.title, window.top navigation), since the code runs
   inside a sandboxed iframe.
3. Avoid external CDN scripts unless I ask for one specifically;
   prefer vanilla JS.
4. Keep CSS scoped to a wrapping <div> with a unique class so it
   doesn't leak into the rest of the Confluence page.
5. Add a short comment at the top explaining what the code does.

Here's what I want to build:
[describe your request here]

If you're using HTML Macro specifically, this same prompt structure is already built in: the macro editor has a "Generate with AI" option that produces a ready-to-copy version of this prompt for you.

How to use it

1. Copy the prompt above (or the built-in one, if you're using HTML Macro).
2. Replace the placeholder line with your actual request (e.g., "a collapsible FAQ list," "a status dashboard pulling from a table on the page," "a countdown timer for a launch date").
3. Paste the generated code into the HTML macro editor.
4. Preview the page. If something doesn't render as expected, tell the assistant what broke. It can usually fix sandboxing issues in one follow-up.

Here's what that looks like in practice: a simple to-do list, generated this way, pasted into the editor with the live preview updating automatically.

And the same widget once published, fully interactive on the live page.

Why the constraints matter

Most AI-generated front-end code assumes a normal browser context. Telling the assistant up front about the iframe sandbox and the lack of a build step heads off the two most common failure modes: scripts that silently fail because they touch something outside the sandbox, and CSS that unexpectedly restyles surrounding Confluence UI. Naming the constraint is more reliable than asking the assistant to "make it compatible with Confluence," which it can't verify on its own.

A couple of things worth trying

• Interactive checklists or forms that store state in the page using localStorage scoped to the wrapping div.
• Simple data visualizations (bar charts, progress bars) built with plain SVG rather than a charting library, since external scripts are best kept minimal.
• Embedded countdowns or timers for launches, sprints, or events.

Have a prompt structure that's worked well for a different app or macro? Drop it in the comments. Always interested to see what others have found.

If you want to see the macro in action or try it yourself, you can find HTML Macro for Confluence on the Atlassian Marketplace.