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. The code examples are split into HTML, CSS and JavaScript, matching the editor's three tabs.

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 "unknown macro"	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 an HTML from Attachment macro for this:

1. Attach the .html file to the Confluence page, or upload it from your computer in the macro.
2. Insert the HTML from Attachment macro and pick the file.
3. Publish. The file renders on the page, sized to its content, with the same security rules as any other macro.

When the report is regenerated, replace the attachment to show the new version, with no copying and pasting of generated code.

---

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 embed interactive charts with Chart.js 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. After migration, those pages show an "unknown macro" error in Cloud.

HTML Macro+ recognizes both the Server/Data Center HTML macro and the Macro Toolbox for Cloud HTML macro. Once it's installed on your Cloud site, migrated pages render again without editing them one by one. You can then scan a space for the old macros, preview what will change, and convert them in bulk to the current macro. Pages stay live throughout.

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.

---

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 content stays inside Atlassian.

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