Atlassian Tools
How to embed HTML into a confluence page
•
min read
To embed HTML in Confluence page, install an HTML macro app from the Atlassian Marketplace, such as HTML Macro for Confluence by Narva Software, embed externally hosted HTML with /embed or an iframe app, or use a code block to display HTML as text without rendering it. Confluence Cloud has no native HTML macro, so every rendering option runs through an app or an embed.
3 ways to add custom HTML to a Confluence Cloud page
The three working Confluence HTML macro alternatives are a Marketplace app, an external embed and a code block, and only the first two render HTML. Pick based on whether you need rendering, JavaScript and admin involvement.
Method | Renders HTML | JavaScript support | Admin needed | Cost | Best for |
1. HTML Marketplace app | Yes | Yes, in a sandboxed iframe (varies by app) | Yes, to install | Free tier or per-user licence | Custom widgets, custom CSS, inline forms |
2. Embed hosted HTML ( | Yes, from an external URL | Yes, on the hosted page | No for | Free, plus hosting | Dashboards, existing web tools, large pages |
3. Code block | No (display only) | No | No | Free | Documentation and code samples |
Method 1: Install an HTML Marketplace app
Find the app. Open the Atlassian Marketplace, search for "HTML macro" and filter by Confluence Cloud. Compare ratings, install counts and look at which Atlassian trust signals does the app have. It is also important to check if the app developer company has the SOC 2 Type II certification to ensure the data protection and integrity.
Install it. A site admin selects Get it now, reviews the requested scopes and approves the installation. Most apps include a 30-day free trial.
Insert the macro. Open the page in edit mode, type
/, search for the app's macro name and select it.Paste your HTML. Add your markup, styles and scripts in the macro editor. Use the preview to check layout.
Publish. Set the frame height if the app asks for one, then publish the page.
Note on sandboxing: the app renders your code inside an iframe. Your CSS styles only the content in that frame, not the surrounding Confluence page. This is also how Confluence custom CSS works in Cloud.
Method 2: Embed hosted HTML with an iframe or Smart Link
To embed HTML in Confluence Cloud without writing it into the page, host the HTML at a URL and insert it with /embed. The page stays in your control, and Confluence displays it in a frame.
Host the page. Publish the HTML file on a web server, static host or internal portal your readers can reach.
Check frame headers. The host must allow framing. An
X-Frame-Options: DENYheader or a restrictive CSPframe-ancestorsrule blocks the embed (see MDN: X-Frame-Options).Insert the embed. Type
/embed, paste the URL and choose the embed view.Size the frame. Drag the handles or set width and height. Without a set size, an HTML iframe defaults to 300 × 150 pixels, per the MDN iframe reference.
When /embed falls back to a plain link, use a Confluence Cloud iframe app from the Marketplace. These apps give you a raw iframe with explicit width, height and scrolling controls.
Method 3: Show HTML as code (no rendering)
Use a code block when readers need to see HTML, not run it. Type /code, paste the snippet and set the language to HTML for syntax highlighting.
Works on every Confluence Cloud plan, including Free.
Needs no admin action and no app.
Carries zero script risk because nothing executes.
Choose this for developer documentation, email templates and style guides.
What can you do with the HTML Macro for Confluence app?
HTML Macro for Confluence by Narva Software lets Confluence Cloud editors write HTML, CSS and JavaScript directly on a page and see it rendered, with no external hosting. It brings back what the Server HTML macro offered, inside a secure frame.
What teams build with it:
Styled knowledge base pages. Create custom navigation, card layouts and landing pages that native macros cannot produce. Start with our guide, How to Create a Knowledge Base in Confluence: A Step-by-Step Guide.
Interactive elements. Add calculators, tabs, accordions, filters and forms with JavaScript.
Custom branding. Apply your own fonts, colors and spacing with CSS inside the macro.
AI-powered content. Connect pages to AI features for search and answers. See How to Build an AI-Powered Confluence Knowledge Base with HTML Macro.
Permissions, security and limits
In Confluence Cloud, only site admins install apps, while any editor can use an installed HTML macro unless the admin restricts it.
Who installs: site admins (or org admins) install and remove Marketplace apps. Editors can request an app from the Marketplace listing.
Script restrictions: to add JavaScript to a Confluence page, you need an app that supports it. Native pages strip
<script>tags and inline event handlers.CSP and sandboxing: Forge apps run in an iframe with the
sandboxattribute and a CSP. Scripts cannot read the parent page, the user's session or other Confluence content.Data residency: Atlassian offers data residency for Confluence Cloud in regions such as the US, EU and Australia. Check that the app also supports your region, or that it stores no data outside Atlassian.
App vetting: prefer apps with the "Runs on Atlassian" badge, a published security policy and participation in the Atlassian Marketplace Bug Bounty program.
Nar is the founder of Narva Software and a former software developer with real-world experience using Atlassian tools. After facing the limitations of Jira and Confluence himself, he set out to build simple, effective apps that make teamwork easier. Today, his focus is on creating practical solutions that help teams work faster and smarter — and are trusted by companies around the world.
