Documentation

Last updated 03/11/2026. HTML Block is a Confluence Cloud app that renders HTML, CSS and JavaScript on Confluence pages. This guide walks an admin through installing it and setting the site's guardrails, and walks every author through inserting, writing, editing and publishing a block.

1. Before you start

1. Confluence Cloud. HTML Block works on Confluence Cloud pages and blog posts. It is not available for Confluence Data Center.
2. A Confluence or site admin to install the app and, if you want, set the site guardrails. Everything after that works without admin rights.
3. Edit permission on the page where you want a block. Viewers need nothing extra.

No API keys, no outside accounts and no per-person approval. Once the app is installed, anyone who can edit a page can add a block.

2. Install (admin)

1. Sign in as a Confluence admin or site admin. In Confluence, open Settings (⚙) → Apps → Find new apps, or open the Atlassian Marketplace website. HTML Block is coming soon to the Marketplace.
2. Search for HTML Block, open HTML Block - HTML, CSS & JavaScript for Confluence and choose Get it now (or start the free trial).
3. Choose your Confluence site and review the permissions. HTML Block asks to read page attachments (so a block can render an attached HTML file) and to keep its own guardrail settings. It asks for no write permissions on your content. Confirm.
4. Sites with up to 10 users are free. Larger sites start a 30-day free trial; billing is handled by the Atlassian Marketplace.
5. Done. Anyone who can edit a Confluence page can now insert an HTML Block. Continue to section 3 if you want to limit what blocks may do.

3. Set site guardrails (admin)

Guardrails apply to every HTML Block on the site. Out of the box, JavaScript is allowed and authors may use any profile up to Trusted. Change them before or after people start writing blocks.

1. Sign in as a Confluence admin and open Settings (⚙) to reach Confluence administration.
2. In the left sidebar, under Apps, choose HTML Block. The guardrails page opens.
3. Allow JavaScript: switch it off to stop author JavaScript running anywhere on the site. Blocks saved with the Trusted profile then render without scripts. Switch it on to let authors run JavaScript on Trusted blocks.
4. Maximum safety profile: choose the loosest profile any block may use.
   • Strict: blocks can only use formatting markup - no scripts, embeds or forms anywhere.
   • Standard: blocks may use iframes, embeds and forms; scripts are always removed.
   • Trusted (no limit): authors may choose any profile, including Trusted with JavaScript.
5. Each change saves straight away and the page shows Saved. There is no separate save button.
6. Settings apply the next time a page renders. Blocks saved with a looser profile than the cap render at the cap, and their authors see a notice in the editor explaining why.

Authors can always choose a stricter setting on an individual block, never a looser one than the guardrails allow.

4. Insert your first block

1. Edit a Confluence page (or blog post) and place your cursor where the block should go.
2. Type /HTML Block and press Enter, or open the + insert menu and search for HTML Block.
3. A full-screen editor opens with the code tabs on the left and the live preview on the right.
4. Write your code (section 5) or choose an attached file (section 7).
5. Choose a Safety profile and a Height at the bottom of the editor (section 6, section 8).
6. Choose Save. The editor closes and the block appears in the page.
7. Publish (or update) the page. The block now renders for every viewer.

Try this to see it working: paste <h2>Hello</h2><p class="note">Rendered by HTML Block</p> into the HTML tab and .note { color: teal; } into the CSS tab.

5. Write code in the editor

• HTML, CSS and JS tabs: each language has its own tab with syntax highlighting, line numbers, bracket matching and undo history. A dot on a tab means it has content.
• Write code or Attached file: the source switch at the top chooses between code you write and an HTML file attached to the page.
• Live preview: the right-hand pane updates a moment after you stop typing and shows exactly what the published page will show, including the safety profile.
• Size counter: the header shows the combined size of your HTML, CSS and JavaScript. The limit is 100 KB per block; Save is disabled while you are over it.
• Cancel closes the editor without changing the block.

6. Safety profiles and JavaScript

Every block has a safety profile, chosen at the bottom of the editor.

1. Choose Strict, Standard or Trusted. Profiles looser than your admin allows are not available.
2. If the profile removes anything, for example a <script> tag under Standard, the preview shows a banner listing exactly what was removed. Choose a looser profile if that content should render.
3. To run JavaScript, choose Trusted and turn on Run JavaScript. This only works if a Confluence admin allows JavaScript on the site (section 3).

JavaScript not running? Code in the JS tab runs only when the profile is Trusted, Run JavaScript is on and the site allows JavaScript. Whenever the JS tab has code that will not run, the preview shows a yellow notice saying which of the three is stopping it.

Every block renders in its own isolated sandbox. Even allowed JavaScript cannot read Confluence data, cookies or anything outside its own block.

7. Render an attached HTML file

1. Attach an .html or .htm file to the page (paperclip menu or drag and drop). Files up to 10 MB are supported.
2. Open the block editor and switch the source from Write code to Attached file.
3. Choose the file from the list. If the list says no HTML files are attached yet, attach one, then reopen the editor.
4. Optional: use the CSS and JS tabs to restyle or script the attached markup. The block's safety profile still applies.
5. Choose Save and publish the page.

Each viewer reads the file with their own Confluence permissions. Someone who cannot see the attachment sees a "no permission" notice, never the content. HTML Block cannot include HTML from a web address: that is deliberate, so your content never has to leave Atlassian. Attach the file instead.

8. Height

• Auto (default): the block grows and shrinks to fit its content.
• Fixed: set an exact height between 40 and 4000 px. Content taller than that scrolls inside the block.

9. Paste in a whole web page

1. Put the page's markup (what is inside <body>) in the HTML tab.
2. Put the contents of its stylesheet in the CSS tab.
3. Put the contents of its script in the JS tab, then follow section 6 to let it run.

Links to separate files such as <link rel="stylesheet" href="style.css"> or <script src="script.js"> cannot load inside a block, because there are no such files here. The preview lists any it finds so you can move that code into the tabs.

10. Edit, copy or remove a block

1. Edit: in page edit mode, select the block and choose Edit from its toolbar. The editor reopens with your saved code and settings. Make changes, choose Save, then update the page.
2. Copy: copy and paste the macro like any other Confluence content, including to another page. Its code travels with it. An attached-file block needs the same file attached on the new page.
3. Remove: delete the macro from the page. HTML Block keeps nothing outside the page, so there is nothing else to clean up.

11. What every viewer sees

• The block exactly as it looked in the preview, at the safety profile the site allows.
• If a site admin has since tightened the guardrails, the block renders at the new limit the next time the page opens.
• Attached-file blocks show the file only to viewers who can see the attachment.
• No sign-in step and nothing to approve: viewers just open the page.

12. Permissions and your data

• Permissions: read page attachments, and keep the app's own guardrail settings. No write access to your pages, spaces or users.
• Your code: saved inside the Confluence page itself, like any other macro, and covered by your Atlassian agreement.
• What the app stores: only the two guardrail settings, in Atlassian-hosted app storage. No page content and no personal data.
• Nothing leaves Atlassian: no outside servers, analytics, tracking, AI or third parties. HTML Block is eligible for Runs on Atlassian.

Full detail: Privacy and Security.

13. Limits

14. Messages and fixes

15. Uninstall

1. A Confluence admin opens Settings (⚙) → Apps → Manage apps.
2. Find HTML Block and choose Uninstall.
3. Blocks on pages stop rendering. The guardrail settings are deleted by Atlassian along with the app. Your code remains in the pages until you remove the macros.

16. Get help

• Support portal: Wattlebrooks Apps support
• Email: support@wattlebrooks.com
• More: Support · Privacy · Security