HTML Include Macro

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 Autocomplete for links, files, macros and mentions.

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).

Parameter Required Default Description
Yes None The 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 Resolved .

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

Was this helpful?

Thanks for your feedback!

16 Archived comments

  1. User avatar


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

    24 Mar 2011
  2. User avatar

    Ed Johnson

    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?


    04 Jan 2012
  3. User avatar

    Harald Holzner

    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?


    01 Mar 2012
    1. User avatar


      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)

      24 Apr 2012
  4. User avatar


    No support at all? Get rid of this product!

    28 Mar 2012
  5. User avatar


    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)

    14 May 2012
    1. User avatar


      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.

      15 May 2012
  6. User avatar


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

    03 Jan 2013
  7. User avatar


    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.

    19 Jul 2013
  8. User avatar

    Sachin Singh


    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?



    16 Mar 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      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.

      16 Mar 2015
  9. User avatar


    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.

    19 May 2015
  10. User avatar

    Craig Skipsey

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

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

    26 May 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Craig,

      The HTML Include macro will unfortunately only return HTML pages. You can include images from the web, but I'm not aware of a way to include office docs that aren't attached to a Confluence page.

      29 May 2015
  11. User avatar



    I am unable to include Sharepoint Link, Could you please let me know how can this be achieved. 

    It shows me with Page not permitted error, whereas i don't have any restrictions on either of the pages.



    10 Jul 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Akash,

      I'd recommend you contact support about this; they can help you troubleshoot the problem if necessary.

      20 Jul 2015
Powered by Confluence and Scroll Viewport