Documentation for Confluence 5.4.
Documentation for Confluence OnDemand 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 content of an HTML file in a Confluence page. This page tells you how to enable the macro, so that it is available on your Confluence site. For help on using the macro, see HTML Include Macro.

CAUTION: Including unknown HTML inside a web page is dangerous.


Because HTML can contain active scripting components, it would be possible for a malicious attacker to present a user of your site with script that their web browser would believe came from you. Such code could be used, for example, to steal a user's authentication cookie and give the attacker their Confluence login password.

(warning) The information on this page does not apply to Confluence OnDemand.

Enabling the HTML Macros

By default, the HTML macros are disabled. You should only turn on these macros if you trust all your users not to attempt to exploit them.

(info) You need to have System Administrator permissions in order to perform this function.

To enable the HTML macros,

  1. Choose the cog icon  at top right of the screen, then choose Confluence Admin.
  2. Select 'Plugins' in the left-hand panel. This will display the installed plugins active for this Confluence installation.
  3. Click' 'HTML macros', then click 'Enable Plugin'.

If the plugin is already enabled please click on the + sign to expand the modules. Ensure that each relevant module is enabled by hovering over the "disabled" dialog and clicking the enable button that appears.

To embed an external page,

Use the following syntax:

To include HTML inline,

Use the following syntax:


HTML Include Macro


  1. Does this enable HTML inside comments, or just pages?

  2. Looks like it does. That's unfortunate. It would be nice to be able to have a space with HTML enabled that was mostly read-only except for comments (which wouldn't allow HTML).

  3. I am currently using confluence 1.3.5. I enabled HTML Macros in the Plugin Manager from the Administration Console. Unfortunately, I am still unable to edit the pages with HTML. <h1> Biggest </h1> won't work. Any idea?

  4. The syntax for html-include macro is not listed anywhere in the documentation that I can find. However, Charles (on the mailing list) reports that the syntax is as follows:

    The syntax to embed an external page is:


    The syntax to include HTML inline is:

    <b>I like cheese</b>

    This should really be included somewhere in the documentation.

  5. Why not give an option to enable it for administrators only?

    1. What would happen when a non admin edited the page and tried to save it? They would then be unable to save the page - even if its just a typo change! It's a nice idea in theory but doesn't work in practice.

      What would be better is the ability to enable / disable macros on a space by space basis as well as site wise. Disabling the plugin at the site level would disable it across the board, but if its enabled that means that space admins could disable the macro in their scope.

    2. Thats the way it works at the moment. You need to be an administrator to be able to enable and disable macros.

  6. Is it possible to include the contents of an HTML file that has been attached to a page? I've tried using a URL to the attachment, but get a This request requires HTTP authentication () error. Any ideas on how to do this?

    1. Hi Jonathan,

      There is currently no way to do this. I have created a feature request for this: CONF-4844


  7. Wouldn't it be possible to add some parameter to html-include that escapes all html (and script) content, effectively converting the external page to raw text?

    What I'm looking for is a way to include some external file (possibly even on an ftp server) in a page. To make the contents of the file harmless, it'd be perfectly ok for confluence to escape all < and > characters (similar to <PRE>).

    Perhaps the {html-include} macro could be modified to support more protocols and to escape all contents by default, unless explicitly specified with a parameter to leave all active content (html and scripts) as-is. Maybe the macro would need another name then too (smile)

    For instance:



    {file-include url=


    escapes all html content

    {file-include url=


    equivalent to current html-include

    {file-include url=


    dumps the contents of a file on ftp; escapes html keywords

    {file-include url=


    dumps the contents of a file on ftp - html will be rendered

    For security, monspaced}}preservehtml{{monspaced could be disabled by admins.

    Does any of this make sense?

    1. Erik: This is possible, and has been filed in JIRA as CONF-503.

      While possible, however, it's very difficult to do well, which is why we're waiting until we have sufficient resources available to do it correctly. For some idea how much work you have to do to make HTML safe, have a look at the details of the recent MySpace Javascript exploit here:

    2. Oops, sorry, I misunderstood your question. A file include that completely sanitizes all HTML tags would definitely be possible, and wouldn't require nearly as much work. If you want to see this in Confluence, please file a feature-request in JIRA.

      1. Preserving HTML layout when importing a file in a page may be nice, but certainly no requirement (for me). It's probably the content that matters, the rest is noice. Help keep the signal to noice ratio high (wink)
        It'd like to use this file-include for example to display the contents of configuration files on a page, or some log file. Should there be any html tags in a file, it's ok if the macro sanitized them by replacing < and > by < and >

        1. In that last sentence I meant "...replacing < and > by &lt and &gt "

  8. HTML Plugin might help with some of these requirements. Feedback would be appreciated.

  9. Is there any way of preserving the styles that are provided by the included page? Whenever I include a page from another one of our servers (ie. not a Confluence page) the resultant page is "confluence-ised" --> loosing colours, fonts, icons, etc.

    1. Rob,

      Can you please submit a bug at detailing specifically what html markup/styles are being overridden (as per this issue: This will help us investigate this problem for you.


      1. I'm not a markup-man, so I've just added some screen shots that show the problem. Please see

  10. Hi,

    Iam new to confluance iam abel to enabel HTML Macros (iam using Confluence 1.1). But now i want to add my external site to confluance search . In usage it's quoted as

    , where i want to add this code to enabel external searc.
    Thanks in advance

    1. Hi Gangadhar,

      Did you mean that you want Confluence to perform search on the embedded external sites? There is a feature request, CONF-5645 which might be of your interest. If you think it addresses your need, feel free to cast a vote and add yourself as a watcher to get its updates.


  11. Anonymous

    can we include HTTPS web site ???

    If yes , How ??

     I was trying to include HTTPS site but giving error

    1. Hi,

      This may be due to your Confluence instance do not trust the certificate of the HTTPS site. There are some existing documentations regarding this that you may be interested to look at:

      If the above is not helpful, feel free to raise a support ticket for further assistance.


  12. Anonymous

    Hey, is it possible to format the embedded html?  I'd like to control the height and width of the embedded page.  I'm fairly new to this stuff so there's probably an entirely better way.  Any direct would be greatly appreciated!

    1. Hi,

      This feature is not supported in Confluence. However, if you are keen to have this feature in the next release version of Confluence, you can raise a feature request and cast the vote at our issue tracker:


  13. The name of the Macros has changed so the instructions are incorrect.  The macros are now under: "Confluence HTML Macros"

  14. Anonymous

    Is it possible to pass parameters to a regular URL (e.g. ). I have complex set of parameters that I would like to pass to the URL. Also, I assume it supports port number in the URL syntax...

  15. Anonymous

    I was refereing to html-include plugin/macro in above question as I would like to display the page.

    1. As far as I am concerned, you can pass the parameters through the URL itself, provided that the target page recognises it. For instance, the parameter "s=T" in the example link. Also, there should not be any problem in supplying URLs with port number (e.g. http://servername:8080/mypage.html) as long as it is accessible by your web browser.

      1. Anonymous

        I have yet to get this to work. My page (a teamcity deployment) uses both parameters

        and a port, and i have whitelisted everything for the purpose of testing however every

        page renders with the error "Could not retrieve http://teamcity:8111/viewType.html?buildTypeId=bt4095&tab=buildTypeStatusDiv - Page not permitted. Internal Server Error"

        The markup code used is:

        Unknown macro: {html-include}

        Should this work, and what happens with a page that is heavily relying on the graphical content of the page?

        Kind regards


  16. Anonymous

    I am trying to generate client stubs for remote SOAP API and I am getting the following error.Has anybody did generate stubs ?

    wsdl2java -uri -d xmlbean
    error is below
    Using AXIS2_HOME: C:\axis2-1.4.1
    Using JAVA_HOME: C:\Program Files\Java\jdk1.5.0_18
    Retrieving document at '
    ERROR Part 'fault' of fault message '

    Unknown macro: {[http}

    InvalidSessionException' must be defined with
    'element=QName' and not 'type=QName'
    ERROR Part 'fault' of fault message '

    Unknown macro: {[http}

    InvalidSessionException' must be defined with
    'element=QName' and not 'type=QName'
    org.apache.axis2.AxisFault: Part 'fault' of fault message '

    Unknown macro: {[http}

    must be defined with 'element=QName' and not 'type=QName'
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.addQNameRefer
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateBindi
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateEndpo
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateEndpo
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateServi

  17. I have followed the instructions to enable the

    macro, but I keep getting a broken link:

    . What could be wrong? Thanks.

    1. Hi Gina,

      You might want to check if the html-include module is enable. You can do check the module via Confluence admin >> Plugin >> Confluence HTML Macros. Click on the Confluence HTML Macros and see if the html-include module is enable.

      Hope that helps.
      Best rgds,

      1. Zed,

        You're right -- it was enabled.  It works now. Thanks very much!


  18. Anonymous


    We are using version 3.1. I have enabled the HTML macro and I have attempted to include a page from our intranet. I get the following error;

    "Could not retrieve http://wisdom/pages/toolbar/menu.html - Page not permitted."

    I first thought this was due to whitelisting. So I disabled everything except for the html-include part of the macro. When I go to the page externally it looks fine so im not sure why this is happening. Any ideas?

    1. Anonymous


      We are using Confluence 2.10.1 and I have the same issue. I'm trying to include  a page from our intranet and have the same error, I guess it's because page has authorization mechanism.

      But how to include such a page to wiki page ? (Basically how to pass a username/password parameter inside for example htlm-include macro ? )

      Haven't able to find a solution for the time being.

      Would be very gratefull for any help.

  19. Anonymous


    I want to embeding a external PDF-File. The content of the file should be searched by confluence search. Is that possible?

    Thank You for any help


  20. html-include to internal sites works. However html-include to external sites does not work.

    Does html-include require the Confluence server to have access to the external site?
    My browser has access via a proxy.
    Do I need to configure a proxy for Confluence?

  21. Is there a way to include the content of an external website without banners videos posted. I just want the contents from the external site. Is this possible?

  22. Anonymous

    Someone back in Sept 2010 commented on a problem I am currently having. Can you please help?

    We are using version 3.4.8 and I have enabled the HTML-include macro. I have attempted to include a page from our intranet and I get the following error;

    "Could not retrieve http://intranet/intranet/blog/ - Page not permitted."

    I first thought this was due to whitelisting so got the rules pattern added http://intranet*. But I'm still getting the error. When I browse to the page on our intranet it is fine. There is no authorisation mechanisms on these blog pages as they are rolled out company wide.

    Appreciate any advice.

  23. Anonymous

    Is there a way to link directly to an HTML resource? I.e. file://<path>/<file>.html, which would work in a web browser, but this macro complains it doesn't know how to do it. Any other way of doing it?

    1. bleh. logged in as anonymous...

  24. Anonymous


    We have confluence 4.3.6. Under system plugins Confluence HTML macros is disabled. Under user Plugins we have BOB Swift Confluence  HTML plugin enabled.

    in one of our 4.3.6 page we receive error "Unknown macro: {html-include}" is that due to Confluence HTML macro disabled ?

    Will Bob Swift will not fix this ?



  25. Anonymous

    It appears that any html-include'd page that does NOT have anonymous authentication enabled causes the Page Not Permitted error. This is a VERY limiting factor and I'm disappointed that there is no way to truly pass the HTML through untouched.

    For my instance, I have a site on port 80 that allows anonymous authentication, and another on port 81 that requires Active Directory authentication to our domain. The anonymous authentication works just fine; the AD-authenticated site doesn't work. 

  26. When I go in confluence admin, i don't see "'Plugins'" , the only item has plugins mentions is "Gliffy Plugin Administration".  Is there new instructions for enabling Html macros?

  27. This documentation is outdated.

  28. Anonymous

    We are trying to include a page on Confluence within another of the same confluence.

    I almost made it with this command on the main page:

    {html-include: url = https://url-page}

    If the url I put it in a public page, it works perfect.

    But when I include a url of the same confluence, the result is that asking for the password and then I redirected to the page you want to include, but leaving the page. That's not what I want to happen.

    There is a solution to this problem?

    Greetings and thank you very much

    1. html-include is for public web pages only.

      For including confluence pages from the same confluence instance, use the include macro.

      (For including confluence pages from other confluence instances, I think it won't work in any way)

      1. Anonymous


        It works perfectly!! 

        Bye!!! And best regards!!

  29. Anonymous

    I don't see "'Plugins' either

  30. This doc page is outdated. Plugins was renamed to Add-ons but there is no HTML macros in search results. Please fix this doc.