This page last changed on Aug 08, 2006 by ivan@atlassian.com.
The {html-include} macro allows you to include the contents of an HTML file in a Confluence page. The {html} macro allows you to include snippets of HTML within an existing page.
Why are they disabled?
Including unknown HTML inside a webpage 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.
You should only turn on these macros if you trust all your users not to attempt to exploit them.
How do I enable them?
You will need:
- Confluence 1.1 or later
- Instructions for 1.0 are included below
- Global "Administrate Confluence" permissions
Instructions:
- Go to the Administrative Console and click on the Plugins section
- Select the "HTML Macros" library
- Click the "Enable Library" link
- If they are not now automatically enabled, enable the specific macros you wish to use
If you are using Confluence 1.0.3a or earlier
You should consider upgrading. It's a free upgrade and there are hundreds of things that we have added, fixed or improved since then.
The instructions below are historical documentation that applies only to Confluence 1.0.3a and earlier. If you are using Confluence 1.1. or later, use the instructions above.
Find the file wikiSubsystemContext.xml. It will be in the application's WEB-INF directory. You will find the following lines commented out.
<!-- <entry key="html-include"><ref local="htmlIncludeMacro"/></entry>-->
<!-- <entry key="html"><ref local="html"/></entry>-->
Remove the XML comments as shown below, and restart Confluence. The macros should now be available.
<entry key="html-include"><ref local="htmlIncludeMacro"/></entry>
<entry key="html"><ref local="html"/></entry>
Confluence 1.1 will allow the site administrator to enable and disable macros from within Confluence without editing any files.
Usage
Example - To embed an external page
Does this enable HTML inside comments, or just pages?

Posted by emulder at Feb 23, 2005 13:31
|
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).

Posted by emulder at Feb 23, 2005 13:34
|
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?

Posted by mclai at May 03, 2005 14:01
|
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.

Posted by jnolen at Aug 23, 2005 12:38
|
Why not give an option to enable it for administrators only?

Posted by johnmblack at Nov 10, 2005 09:25
|
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.

Posted by dhardiker@adaptavist.com at Nov 10, 2005 09:30
|
Thats the way it works at the moment. You need to be an administrator to be able to enable and disable macros.

Posted by daniel@atlassian.com at Nov 13, 2005 17:32
|
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?

Posted by jwilson@lohika.com at Dec 02, 2005 12:29
|
Hi Jonathan,
There is currently no way to do this. I have created a feature request for this: CONF-4844
Regards,
-Daniel

Posted by daniel@atlassian.com at Dec 05, 2005 23:04
|
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 
For instance:
For security, monspaced}}preservehtml{{monspaced could be disabled by admins.
Does any of this make sense?

Posted by erik.van.zijst at Jan 13, 2006 03:44
|
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

Posted by cmiller at Jan 17, 2006 17:19
|
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.

Posted by cmiller at Jan 17, 2006 17:21
|
CONFEXT:HTML Plugin might help with some of these requirements. Feedback would be appreciated.

Posted by bob.swift@charter.net at Jan 17, 2006 23:37
|
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 
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 >

Posted by erik.van.zijst at Jan 18, 2006 03:10
|
In that last sentence I meant "...replacing < and > by < and > "

Posted by erik.van.zijst at Jan 18, 2006 03:13
|
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.

Posted by rob.whitney@adi-limited.com at Jun 16, 2006 01:50
|
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

Posted by dave@atlassian.com at Jun 18, 2006 19:24
|
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

Posted by rob.whitney@adi-limited.com at Jun 18, 2006 20:50
|
Can this macro support pictures? For example, I do Unknown macro: {html-include} and the google banner is broken.

Posted by zcarter at Aug 22, 2006 20:27
|
No Zac, you can't include the actual image withing a Confluence page via using of the {html-include} macro. It will be attempted to render and resulting in unreadable content. The html-include macro is intended to include html content only.
Thanks,
Iva

Posted by ivan@atlassian.com at Aug 23, 2006 00:55
|
|