HTML Macro Pro for Confluence
Embed websites and custom HTML code in Confluence
This Macro allows you to securely add custom code (HTML, Javascript, CSS) into your Confluence pages.
Introduction
Welcome to the user guide for HTML Macro Pro. In this guide, we’ll walk you through the features of our extension for Confluence.
HTML Macro Pro for Confluence is a third-party app developed specifically to meet the need for embedding custom code within your favorite Atlassian product.
Is this secure?
Yes, security is a top priority in the design of this macro.
Custom code runs within a secure sandbox, isolated from the user context.
Confluence administrators have full control over allowed content by setting Content Security Policies (CSPs) for pages.
Additionally, administrators can restrict which user groups are permitted to add this macro to pages.
Custom code runs within a secure sandbox, isolated from the user context.
Confluence administrators have full control over allowed content by setting Content Security Policies (CSPs) for pages.
Additionally, administrators can restrict which user groups are permitted to add this macro to pages.
Embedding websites
Key features
- Automatic resizing of the iframe to 100% width
- Securely embedded in Confluence using a sandbox that separates user context from the embedded content
- Simple and user-friendly interface
Step by step walkthrough
- Navigate to the page where you’d like to embed a website or URL.
- In the page content, add the HTML Macro by either typing
/html
- Or clicking on the "+" icon in the toolbar and selecting the Macro from the right pane.
- Once added, a popup will appear, prompting you to enter the URL you’d like to embed.
- Optionally, set the height of the embedded content block.
- Click Save. Your Macro block will display a preview message.
- To finalize, click the blue Publish button in the top-right corner of the page.
- You're done!
Edit & Resize
After adding the Macro to a page, you’ll see a set of buttons when hovering your mouse over the block:
- The first button on the left opens the configuration modal, allowing you to change the URL and settings for the block.
- The three buttons in the middle control the maximum size to which the block should resize.
- You can also duplicate the Macro block.
- Finally, the last button, marked with a trash bin icon, allows you to remove the Macro block from the page.
Embedding code
Key features
- Seamless integration of custom HTML, JavaScript, or CSS code within Confluence
- Secure execution within a sandbox, isolated from the user context
- Syntax highlighting for easier editing and readability
Step by step walkthrough
- Follow the same steps as above to add the Macro to the page.
- In the configuration modal, select the Insert raw HTML or JavaScript code option.
- Copy and paste your HTML code into the right pane.
- If adding an iframe, we recommend setting its width and height properties to 100%.
- Click on the save button
- Publish your changes by clicking the blue Publish button in the top-right corner of the page.
- You're done!
Managing Security
Key features
- Set custom Content Security Policies (CSPs) to control what users can do with this Macro.
- Access a template library of predefined rules for common integrations used within Confluence.
- Restrict Macro usage to a specified list of user groups.
Step by step walkthrough
- In the top menu, go to Apps > Manage apps.
- In the left menu, find HTML Macro Pro for Confluence.
- You will see the main settings screen.
Content Security Policy
By default, the Macro does not restrict embedded content on your Confluence pages.
While this is convenient, it may not comply with your company’s security policies.
In this settings screen, you can fine-tune which resources and content are allowed on pages.
While this is convenient, it may not comply with your company’s security policies.
In this settings screen, you can fine-tune which resources and content are allowed on pages.
- Choose from a predefined ruleset or define your own Content Security Policy.
Managing user groups
You can restrict which user groups are allowed to embed external content within Confluence.
- In the Settings page, click on the User Permissions tab.
- Select the groups you want to grant this Macro access to and click Save.
- You're done!
Troubleshooting
Content Security Policy violation
If you encounter this error while loading a Confluence page containing our Macro, it means that certain restrictions have been applied to what the Macro is allowed to do.
This typically occurs when the Macro attempts to embed an external website (e.g., within an iframe) and the source has not been explicitly approved in the Macro settings.
If you are a Confluence Administrator, please follow the steps outlined in the Managing Security section.
This typically occurs when the Macro attempts to embed an external website (e.g., within an iframe) and the source has not been explicitly approved in the Macro settings.
If you are a Confluence Administrator, please follow the steps outlined in the Managing Security section.
The Macro does not load
This behavior can happen on mainly three different reasons :
- The Macro attempts to load a URL that does not exist (404 error).
- You do not have permission to load the URL (403 error).
- Most likely, the website refuses to be embedded.
Some websites, SaaS platforms, or other external services may enforce a Content Security Policy (CSP) that prevents embedding their content into any other platform, including Confluence pages.
In the latter case, there is unfortunately nothing we can do, This restriction is beyond our control and cannot be bypassed. If embedding the content is critical to your workflow, we recommend reaching out to the website or service provider to inquire about whitelisting for embedding purposes.
.png)