Search the Confluence 4.1.x Documentation:

Index
Downloads (PDF, HTML & XML formats)
Other versions

This documentation relates to Confluence 4.1.x
If you are using an earlier version, please view the previous versions of the Confluence documentation and select the relevant version.
Skip to end of metadata
Comment: Corrected links that should have been relative instead of absolute.
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. Go to the Confluence 'Administration Console':

    • Choose Browse > Confluence Admin. The 'Administrator Access' login screen will be displayed.
    • Enter your password and click Confirm. You will be temporarily logged into a secure session to access the 'Administration Console'.
  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'.


To embed an external page,

Use the following syntax:


To include HTML inline,

Use the following syntax:

RELATED TOPICS

HTML Include Macro

Page: Writing User Macros
Page: Enabling HTML macros
Page: Enabling the html-include Macro
Page: Adding, Editing and Removing User Macros
Page: Include Page Macro

40 Comments

Hide/Show Comments

  1. Feb 23, 2005

    Erin Mulder

    Does this enable HTML inside comments, or just pages?

  2. Feb 23, 2005

    Erin Mulder

    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. May 03, 2005

    mclai

    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. Aug 23, 2005

    Jonathan Nolen

    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:

    {html-include:url=http://www.example.com}

    The syntax to include HTML inline is:

    {html}
    <b>I like cheese</b>
    {html}

    This should really be included somewhere in the documentation.

  5. Nov 10, 2005

    John M. Black

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

    1. Nov 10, 2005

      Dan Hardiker

      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. Nov 13, 2005

      Daniel Ostermeier

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

  6. Dec 02, 2005

    Jonathan Wilson

    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. Dec 05, 2005

      Daniel Ostermeier

      Hi Jonathan,

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

      Regards,
      -Daniel

  7. Jan 13, 2006

    Erik van Zijst

    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:

    macro

    description

    {file-include url=

    http://acme.org/file.html

    }

    escapes all html content

    {file-include url=

    http://acme.org/file.html

    |preservehtml=true}

    equivalent to current html-include

    {file-include url=

    ftp://acme.org/pub/file.txt

    }

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

    {file-include url=

    ftp://acme.org/pub/file.txt

    |preservehtml=true}

    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. Jan 17, 2006

      Charles Miller

      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: http://namb.la/popular/tech.html

    2. Jan 17, 2006

      Charles Miller

      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. Jan 18, 2006

        Erik van Zijst

        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. Jan 18, 2006

          Erik van Zijst

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

  8. Oct 08, 2006

    Bob Swift

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

  9. Jun 16, 2006

    Rob Whitney

    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. Jun 18, 2006

      David Loeng

      Rob,

      Can you please submit a bug at http://jira.atlassian.com detailing specifically what html markup/styles are being overridden (as per this issue: http://jira.atlassian.com/browse/CONF-3273)? This will help us investigate this problem for you.

      Cheers,
      Dave

      1. Jun 18, 2006

        Rob Whitney

        I'm not a markup-man, so I've just added some screen shots that show the problem. Please see http://jira.atlassian.com/browse/CONF-6384

  10. Jul 20, 2007

    Gangadhar

    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
    html-include:url=http://www.example.com

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

    1. Jul 23, 2007

      Fennie Ng

      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.

      Regards,
      Fennie

  11. Apr 02, 2008

    Anonymous

    can we include HTTPS web site ???

    If yes , How ??

     I was trying to include HTTPS site but giving error

    1. Apr 03, 2008

      Tony Cheah Tong Nyee

      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.

      Cheers,
      Tony

  12. Jun 27, 2008

    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. Jul 02, 2008

      Ming Giet Chong

      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:

      Regards,
      MG

  13. Dec 14, 2008

    Stuart Gilberd

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

  14. Mar 12, 2009

    Anonymous

    Is it possible to pass parameters to a regular URL (e.g. http://finance.yahoo.com/q?s=T ). 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. Mar 12, 2009

    Anonymous

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

    1. Mar 15, 2009

      Azwandi Mohd Aris [Atlassian]

      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. Jun 15, 2011

        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

        Jonas

  16. May 19, 2009

    Anonymous

    Hi
    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 http://wikicentral.cisco.com/confluence/rpc/soap-axis/confluenceservice-v1?wsdl -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 'http://wikicentral.cisco.com/confluence/rpc/soap-axis/co
    nfluenceservice-v1?wsdl'.
    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}

    InvalidSessionException'
    must be defined with 'element=QName' and not 'type=QName'
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.addQNameRefer
    ence(WSDL11ToAxisServiceBuilder.java:1245)
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateBindi
    ng(WSDL11ToAxisServiceBuilder.java:776)
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateEndpo
    int(WSDL11ToAxisServiceBuilder.java:538)
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateEndpo
    ints(WSDL11ToAxisServiceBuilder.java:489)
    at org.apache.axis2.description.WSDL11ToAxisServiceBuilder.populateServi

    1. May 19, 2009

      Andy Brook

      Perhaps Confluence Maven2 SOAP library will help.

  17. Jan 22, 2010

    Gina Wadley

    I have followed the instructions to enable the

    macro, but I keep getting a broken link:

    . What could be wrong? Thanks.

    1. Jan 25, 2010

      Zed Yap [Atlassian]

      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,
      Zed

      1. Jan 26, 2010

        Gina Wadley

        Zed,

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

        Gina

  18. Sep 16, 2010

    Anonymous

    Hi,

    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. Mar 04, 2011

      Anonymous

      Hello,

      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. Aug 30, 2011

    Anonymous

    Hello,

    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

    Helmut

  20. Oct 03, 2011

    Tiemco de Jong

    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. Oct 18, 2011

    Diljo Johny

    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. Nov 29, 2011

    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.