5 Ways to Use HTML in Confluence Cloud (With Examples)

Short answer: Confluence Cloud doesn't include an HTML macro. The one you may remember from Server and Data Center was never brought to Cloud, and even on Data Center it's disabled by default. In Cloud you have two options:

• The built-in iFrame macro embeds another web page by URL. It can't run your own HTML, CSS or JavaScript, and many sites refuse to be embedded.
• An HTML macro app from the Atlassian Marketplace adds a macro where you write your own code. It runs in a sandboxed frame, so it can't affect the rest of the page.

This guide uses HTML Macro+ for Confluence, which is free and runs on Atlassian Forge, but the ideas apply to any HTML macro. For a tour of the macro itself, see our Confluence HTML macro overview. The code examples are split into HTML, CSS and JavaScript, matching the editor's three tabs. To insert the macro, edit a page, type /html and select HTML Macro+ for Confluence.

What you want to do	Native Confluence Cloud	With an HTML macro
Style a section beyond the built-in panels	Limited to panels, colors and layouts	Any CSS inside the macro
Embed a video, map or design file	iFrame macro, if the site allows embedding	Your own iframe, wrapped in your own layout
Show an existing .html file	Attach it as a download	Render it on the page
Add interactive elements	Not possible	Any JavaScript, in a sandbox
Keep migrated Data Center HTML pages working	Shows "Error loading the extension!"	Pages keep rendering

---

1. Style a section with custom CSS

When you need it: a landing page for your space, a styled call-out, a grid of link cards, or brand colors that the built-in panels don't offer.

One thing to know first: CSS in an HTML macro styles what is inside the macro, not the whole Confluence page. That's by design, because the macro renders in its own sandboxed frame. It means your styles can't break the Confluence UI, and Confluence's styles can't break yours.

HTML

<div class="cards">
  <a class="card" href="/wiki/spaces/ENG/pages/onboarding">
    <span class="card-kicker">Start here</span>
    <h3>Engineering onboarding</h3>
    <p>Accounts, tools and your first week.</p>
  </a>
  <a class="card" href="/wiki/spaces/ENG/pages/runbooks">
    <span class="card-kicker">On call</span>
    <h3>Runbooks</h3>
    <p>Step-by-step fixes for common incidents.</p>
  </a>
  <a class="card" href="/wiki/spaces/ENG/pages/architecture">
    <span class="card-kicker">Reference</span>
    <h3>Architecture</h3>
    <p>How our services fit together.</p>
  </a>
</div>

CSS

.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 16px;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}
.card {
  display: block;
  padding: 20px;
  border: 1px solid #dfe1e6;
  border-radius: 10px;
  color: #172b4d;
  text-decoration: none;
  transition: border-color 0.15s, box-shadow 0.15s;
}
.card:hover {
  border-color: #0c66e4;
  box-shadow: 0 4px 12px rgba(9, 30, 66, 0.12);
}
.card-kicker {
  font-size: 12px;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.04em;
  color: #0c66e4;
}
.card h3 { margin: 8px 0 4px; font-size: 17px; }
.card p { margin: 0; font-size: 14px; color: #44546f; }

Links inside the macro open through Confluence's own navigation, so internal /wiki/... links behave like normal page links.

---

2. Embed videos, maps and design files

When you need it: a product demo video next to the release notes, an office map on the "Getting here" page, a Figma prototype in the design spec.

The built-in iFrame macro works when the site allows embedding and you only need the embed itself. An HTML macro helps when you want the embed wrapped in your own layout, such as a responsive 16:9 frame with a caption, or several embeds side by side.

HTML

<figure class="embed">
  <div class="frame">
    <iframe
      src="https://www.youtube.com/embed/VIDEO_ID"
      title="Release 4.2 walkthrough"
      allowfullscreen
    ></iframe>
  </div>
  <figcaption>Release 4.2 walkthrough (6 minutes)</figcaption>
</figure>

CSS

.embed { margin: 0; }
.frame {
  position: relative;
  aspect-ratio: 16 / 9;
  border-radius: 10px;
  overflow: hidden;
  background: #091e42;
}
.frame iframe {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  border: 0;
}
figcaption { margin-top: 8px; font-size: 13px; color: #44546f; }

Replace VIDEO_ID with your video's ID. In HTML Macro+, unless your admin allows all domains, youtube.com must be on the domain whitelist; until it is, the frame shows a "Content blocked" placeholder. The same applies to google.com for Maps and figma.com for Figma. See security settings.

---

3. Show an existing HTML file on the page

When you need it: you already have HTML output from another tool, like a test coverage report, a notebook exported to HTML, a generated API reference or a one-page prototype. Attached to a page, it's just a download link that most readers never open.

HTML Macro+ includes a second macro, HTML from Attachment, for this:

1. Edit the page, type /HTML from Attachment and insert the macro. Its editor opens.
2. Drop your .html or .htm file onto the upload area, or click to choose it.
3. Check the content summary and the preview, then click Save and publish the page.

The file's styles are kept with its HTML, so it looks the way it does in a browser, and it renders through the same sandbox and security rules as the main macro.

The macro stores the content of the file you uploaded. It isn't linked to a page attachment, so regenerating the report doesn't update the page on its own. When you have a new version, open the macro's editor and upload the new file; the previous content is replaced when you save. See HTML from Attachment.

---

4. Add interactivity with JavaScript

When you need it: content that's easier to read when readers can switch or filter it, such as tabs for different operating systems, a filterable list, a calculator or a chart.

Here's a small tabbed panel. The same pattern works for any "show one of several" content.

HTML

<div class="tabs">
  <div class="tab-buttons" role="tablist">
    <button class="active" data-tab="mac" role="tab">macOS</button>
    <button data-tab="windows" role="tab">Windows</button>
    <button data-tab="linux" role="tab">Linux</button>
  </div>
  <div class="tab-panel active" id="mac">Install with Homebrew: <code>brew install our-cli</code></div>
  <div class="tab-panel" id="windows">Install with winget: <code>winget install OurCo.Cli</code></div>
  <div class="tab-panel" id="linux">Install with apt: <code>sudo apt install our-cli</code></div>
</div>

CSS

.tabs { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
.tab-buttons { display: flex; gap: 4px; border-bottom: 1px solid #dfe1e6; }
.tab-buttons button {
  padding: 8px 14px;
  border: 0;
  border-bottom: 2px solid transparent;
  background: none;
  font-size: 14px;
  color: #44546f;
  cursor: pointer;
}
.tab-buttons button.active { color: #0c66e4; border-bottom-color: #0c66e4; font-weight: 600; }
.tab-panel { display: none; padding: 16px 2px; font-size: 14px; }
.tab-panel.active { display: block; }
code { background: #f1f2f4; padding: 2px 6px; border-radius: 4px; }

JavaScript

document.querySelectorAll(".tab-buttons button").forEach((button) => {
  button.addEventListener("click", () => {
    document
      .querySelectorAll(".tab-buttons button, .tab-panel")
      .forEach((el) => el.classList.remove("active"));
    button.classList.add("active");
    document.getElementById(button.dataset.tab).classList.add("active");
  });
});

For bigger examples, see how to make a pie chart in Confluence and how to build a status dashboard.

---

5. Keep migrated Data Center HTML pages working

When you need it: you're moving from Confluence Server or Data Center, and some pages were built with the HTML macro or its relatives. After migration, those macros show "Error loading the extension!" when you view the page, and Unknown macro (or the same error) in the editor.

Once HTML Macro+ is installed on your Cloud site, it renders these legacy macros again with their original settings, without editing pages one by one:

• HTML (html)
• HTML Include (html-include), which shows the page at the macro's URL
• Macro Toolbox HTML (Appfusions)

Confluence's editor still can't open legacy macros as they are stored. To make one editable, open the page in view mode, hover the macro and click Migrate to enable editing; you can convert one macro or every legacy macro on the page. Site administrators can also migrate a whole space from the app's Migrate tab, with a dry-run preview first. Each migration saves a new page version, so it can be undone from page history. Details are in Legacy Server/DC Macros.

Before migrating, check which HTML macros use external scripts or images. Those domains need to be whitelisted in Cloud, or the content will show as blocked. The same applies to the sites that HTML Include macros fetch from.

---

HTML macro not working?

Most problems come down to a domain that isn't whitelisted, a script that runs before the page is ready, or restricted editor access. The troubleshooting guide walks through each fix.

---

Frequently asked questions

Can Confluence Cloud render HTML? Not natively. Confluence Cloud has no HTML macro. You can embed other web pages with the iFrame macro, or install an HTML macro app to render your own HTML, CSS and JavaScript.

Why doesn't Confluence Cloud have an HTML macro? Letting any editor run their own code on a page is a security risk, especially cross-site scripting. HTML macro apps handle this by rendering code in a sandboxed frame and letting admins control which external sites can load.

Can I paste HTML into the Confluence editor? Pasting copied web content keeps much of its formatting, but pasting raw HTML code shows it as text. To have code rendered, put it in an HTML macro.

Is it safe to use JavaScript in Confluence Cloud? It depends on the app. Look for sandboxed rendering, an admin-controlled domain whitelist, and editor permissions so only trusted people can change code. HTML Macro+ has all three and runs on Atlassian Forge, so your code is stored in Confluence. External resources such as scripts, images or API calls only load from domains your admin allows.

Does CSS in the macro change the rest of my Confluence page? No. Styles apply only to the content inside the macro.

---

Try it

HTML Macro+ for Confluence is free on the Atlassian Marketplace. Start with the installation guide, then try any example above.

Install HTML Macro+, free on the Atlassian Marketplace