Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

Documentation for Confluence 5.7.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The HTML Include macro allows you to include the contents of an external HTML file (a webpage) in a Confluence page.

HTML macros are disabled by default

The HTML macro will only be available if it has been enabled by an administrator. Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks.

Using the HTML Include Macro

To insert the HTML Include macro into a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.


Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

YesNoneThe URL of the page to include.

Enabling the HTML Include Macro

The HTML Include macro is disabled by default. You'll need Confluence Administrator or System Administrator permissions to enable this macro.

(warning) Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You should only turn on these macros if you trust all your users not to attempt to exploit them. We strongly recommend leaving this macro disabled if you allow self-signed up or anonymous users to create content.

To enable the HTML Include macro:

  1. Go to > Add-ons

  2. Select System from the drop down and search for the Confluence HTML Macros add-on.
  3. Expand the add-on and enable the html-include (html-include-xhtml) module.

Administrators can also choose to use the whitelist to restrict URLs that can be displayed in the HTML Include macro.


  • Administrators can define a whitelist of trusted URLs. If a URL is not in the whitelist, you will see an error message in the HTML Include macro.
  • You can only use the HTML Include macro for pages with absolute links. If you use the macro to include an HTML page that has relative links, you will see a 'Page Not Found' error. See CONF-6567 - HTML Include macro should rewrite relative links to point to remote site Open .

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: html-include

Macro body: None.

Storage format example


Wikimarkup example


  1. Anonymous

    Is it possible to pass parameters to the included web page?  If so, what's the syntax?

  2. I want to include a javascript source code file inline and also add the code macro formatting to it.

    However, linking to a *.js file fails with this macro. It's trying to force links to HTML only. 

    Is there any macro to include source code files?


  3. Is it possible to use local *.html files in this macro?

    e.g. url=file://C:/folder1/folder2/xyz.html (i also imported it to the whitelist) but it doesn't work.

    Can somebody help?


    1. Anonymous

      If you are familiar with Java you could roll your own on the same container under a different web app.. for example if you are using Standalone installation you can configure the Tomcat that is bundled with Confluence to add  new web app in "Confluence Application Folder"\conf\server.xml :

      Then add add a simple index.jsp to your new web app (in the above specified location from the docBase in the context):

      This will allow you to create subfolders in this location on the disk and will automatically display them as HTML links when the JSP is rendered.

      Any files placed in subfolders in this location ending in .html will be created as links using the context path you specified above (e.g. http://confluence/CustomUserContent/Subfolder/SomeIndex.html)

      You can then include this in your whitelisted URLs for the application. The URL will be the DNS for your Confluence installation plus whatever context path  you specified in server.xml (e.g. http://confluence/CustomUserContent)

  4. Anonymous

    No support at all? Get rid of this product!

  5. Anonymous

    For some reason in Chrome this macro just creates blank white space, but in IE it works fine. Any insights?

    I want to have an external HTML page stored on a local disk show up as a frame in a confluence page. To the poster above, you can seemingly use local html files (it seems to work for me). I just have trouble with Chrome...   (this is on confluence 3.3)

    1. Anonymous

      Please can you post a screenshot of the witelist and the settings of the html include macro to show a local html file. Ouer companys workstations are setup with ie9 on windows 7. Thanks.

  6. Anonymous

    https (https://hostname/.....) url is not working there any solution for this issue?

  7. Anonymous

    To display a remote page in Confluence, you can also use the usual HTML-Makro and insert an IFRAME.

    HTML-Makros must be allowed by the admin!



    Step 1: Insert am HTML-Makro to your Page.

    Step 2: Insert the following code into the HTML-Makro:


    Step 3: Save the page.

  8. Hi,

    Can we get Dynamic contents (e.g. Charts, reports etc.) in confluence using HTML include macro?

    if yes then is there any different step to enable it?



    1. Hi Sachin,

      All you need to do with this macro is enter a URL and, as long as it's in your whitelist, it'll display whatever's on the webpage.

  9. For Iframe, I would suggest to use HTML Macro instead. You can define attributes such as width,height with HTML macro. I couldn't figure out how to define them in HTML Include macro. And It's easy to use.

  10. Can you include a document that sits inside a URL?  eg 

    I need search to return results from linked URL's...