Skip to content
Yamuno

Documentation

HTML Macro+ for Confluence
Browse

Frequently asked questions

General

What is HTML Macro+ for Confluence?

HTML Macro+ for Confluence is an Atlassian Forge app that lets you embed custom HTML, CSS, and JavaScript directly inside Confluence pages. It provides a full code editor with live preview and enterprise-grade security controls.

Does it work on Confluence Server or Data Center?

No. HTML Macro+ for Confluence is a Confluence Cloud app only. It runs on Atlassian Forge and is not available for Server or Data Center deployments.

We migrated from Server/Data Center and see "Error loading the extension!" Can this app help?

Yes, for the old HTML Include and HTML macros, and Macro Toolbox's HTML macro. With HTML Macro+ installed they render again with their original settings, and you can migrate them into editable macros from the page or in bulk. See Legacy Server/DC Macros.

Can I move content from another HTML macro app?

Yes. The Migrate tab converts macros from Appfire's HTML Macro, Narva's HTML Tools and Macro Toolbox, or any macro by its key, a space at a time. See Migration.

Is my HTML code stored securely?

Yes. All macro content is stored inside Atlassian's Confluence infrastructure as part of the macro configuration. No content is sent to or stored on external servers. The app runs entirely on Atlassian Forge.

Can viewers see my HTML source code?

No. Confluence page visitors only see the rendered output. The HTML, CSS, and JavaScript source code is never exposed to viewers. Only users with editor access (and admin permission) can open the editor.

Pricing and licensing

Is HTML Macro+ free?

It is free for sites with up to 10 users. Larger sites subscribe through Atlassian, monthly or annually, from $0.30 per user per month and less per user on bigger sites, after a free 1-month trial. See Licensing.

Will my pages stop working if we don't subscribe?

No. Pages always keep showing their content, licensed or not. Without a subscription or trial, macros still render with a short notice above them that the app requires a valid license, and the editor opens but can't save.

How long do we have before a license is needed?

Start the Atlassian Marketplace free trial (1 month) when you take the paid version. Without a subscription or trial, pages keep showing their content, but editing and the app's settings need one.

How do we subscribe or start a trial?

A Confluence admin can subscribe or start a trial in Confluence → Manage apps.

Is there a discount?

Yes. Until 28 February 2027, we're offering 25% off monthly and annual subscriptions. Request the code. See Licensing.

Library

What is the library?

A set of shared building blocks that every macro on your site can use: variables such as {{companyName}}, components such as <ReleaseBanner />, and brand tokens such as var(--brand-primary). See Library.

Who can change the library?

Only Confluence admins, and only from the app's settings. Everyone who can edit a macro can use what is in the library.

Do pages update when a variable or component changes?

Yes. A changed variable value or a newly published component shows on every page that uses it on that page's next view. You don't need to edit the pages.

Can I use variables in JavaScript?

Yes, but not as {{name}}, because scripts are never rewritten. Read the value from window.HTMLMacro.vars.name instead. Inside a component, its settings are in HTMLMacro.props.

I use Vue or Handlebars. Will {{ }} placeholders break?

No. A placeholder the library doesn't know is left exactly as written, so your templates keep working. The editor warns about unknown placeholders in case one is a typo.

Can a variable value inject HTML into a page?

No. Values are escaped, so they can never add markup in HTML or break out of CSS. Link values must start with https://, http://, mailto:, tel:, / or #.

Why can't I delete a variable or component?

A variable or component that a page uses can't be deleted. For a variable, the settings show where it is used, so you can update those pages first.

Editor

Do I need to know HTML to use this app?

Yes, basic HTML/CSS knowledge is required to get the most out of this app. It is designed for teams who need to embed custom layouts, interactive widgets, or branded content that Confluence's native editor cannot produce.

Can I use external JavaScript libraries?

Yes, if your admin has whitelisted the CDN domain in the security settings. For example, to use Chart.js from jsDelivr:

  1. Ask your admin to whitelist cdn.jsdelivr.net
  2. In your HTML tab, include: 
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

Can I use <iframe> to embed YouTube or other content?

Yes. The quickest way is Embed templates in the editor: pick YouTube, Figma, Google Docs, Power BI or another service, paste the link, and the iframe code is written for you. See Embed Templates. You can also write your own <iframe>.

Either way, the domain must be allowed by your admin's security settings, for example youtube.com on the whitelist. If it is not allowed, the iframe is replaced with a blocked content placeholder.

Links in the preview are handled differently from the published page. In the preview, link behaviour may vary. On the published Confluence page, all links route correctly through Confluence's navigation system.

Can I undo a change I saved?

Yes. Click History in the editor to see the last 10 saved versions, preview any of them, and restore it. See Version History & Collaboration.

Can I use fetch() or make API calls?

Yes. JavaScript's fetch() API is available. Note that the target domain must be allowed by the CSP security settings, otherwise the browser will block the request.

Security

What does "Block all" mode mean?

In Block all mode, no external resources (images, iframes, scripts, stylesheets, fonts, media) are loaded. Only inline content and data: / blob: URIs work. This is the most secure mode.

I set Whitelist Only mode but added no domains. Why is everything blocked?

By design. An empty whitelist in Whitelist Only mode is treated the same as Block all. You must add at least one domain to start allowing external resources.

Can I whitelist a subdomain without allowing the root domain?

Yes. Use the *.example.com format to allow subdomains only, without allowing example.com itself.

Will CSP affect JavaScript running inside the macro?

Inline JavaScript (written in the JavaScript tab) always runs regardless of the CSP mode, because it is explicitly permitted. CSP only restricts externally loaded resources like remote scripts, stylesheets, images, and iframes.

Permissions

Can I let some users edit HTML but not others?

Yes. Turn on Restrict editing to whitelisted users and groups in the Permissions settings and add the users, or the Confluence groups, you want to allow. All other users will be blocked from opening the editor.

If a user is blocked from the editor, can they still see the macro output?

Yes. Access control only restricts the editor. The rendered output on the Confluence page is visible to anyone with page view access.

Are Confluence admins always able to edit?

Yes. Confluence site administrators always have editor access regardless of the permission settings.

Need more help?

Guides for HTML Macro+ for Confluence

Stuck on something this page does not cover? Ask the developers.