Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The HTML macro allows you to add HTML code to 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 Macro

To add the HTML macro to 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.

There are no parameters for this macro.

Enter the HTML code into the body of the macro placeholder.

Enabling the HTML Macro

The HTML 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 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 (html-xhtml)  module.

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

Macro body: Text, consisting of HTML code.

Parameters: None.

Storage format example

< ac:structured-macro ac:name = "html" >
   < ac:plain-text-body > <![CDATA[<a href="">Click here</a> to see the <b>Atlassian</b> website.]]> </ ac:plain-text-body >
</ ac:structured-macro >

Wikimarkup example


  1. Anonymous

    we want to add expandable/collapsible headings to our wiki pages. i think a combo of javascript and html is the only way to do this.

    is there also a way to add javascript to your pages?

  2. sorry, the above is me. i am not anonymous, just forgot to sign in.

    1. Hi Mark,

      Perhaps what you require is already implemented by the expand macro. If this is not what you require, you can also create your own user macro in which you can specify your JavaScript. Hope this helps.


      1. The cloak macro is a better alternative. Available in the composition plugin.

  3. Hi,

    I am trying to add an image map using the html macro in Confluence 4.1.

    My image won't display on the page, even though it is attached to the page.  I've checked the file name and it matches the code.

    This is the code I've used:

    <img src="lifecycle.gif" width="300" height="200" usemap="#shapes"/>
    <map name="shapes" id="shapes">
    <area shape="rect"
    title="Rectangle" alt="Rectangle"/>


    Can anyone suggest a fix?


  4. Anonymous


    I have some javascript and css inside the html macro, which works only in preview when adding/choosing the macro from the macro list, vut when i save the page it doesnt work. any idea?


    1. Anonymous

      i too have the same issue.. Have you found out a way to make it work ?




    2. Hi Mr Anonymous, you can browse to Space Tools > Look and Feel > Stylesheet and add the CSS there. Additional information on styling Confluence stylish styles can be distilled from this doc

  5. sample macro for executing javascript for those who need it.

  6. Anonymous

    I have enable the HTML macro. I need to access the logged user's info in that macro. How do I do that?

    1. I have the same question and have been researching this to no avail.  Please advise.

    2. I figured it out!  Just pull the meta data off the page...

      Viewing the source for the page and searching for your user name reveals the meta data elements.  There are several "ajs-" meta data elements that might be useful.

  7. We use phpchart on another webserver.  I want to include a page that generates a graph.

    I can include the php page but the graph is not rendered.  The graph renders via javascript.  Can I do this the html macro?

    1. The PHP script needs to be served from a CGI type server, then do xmlhttprequests from your javascript or whathave you in the macro


  8. my html macro works only on the preview but not after i save the page ? Why

  9. Hi I too have a same problem.. I have a HTML code inside the HTML macro with some CSS file inside the head of HTML.

    It works fine when i preview it. But the same is not reflecting when i save it.

    kindly help me.

    1. Are you using the Atlassian HTML macro or HTML Plugin for Confluence? If the later, then use head=true and make sure you are on version 4.1.0 or above.

  10. Hi Bob

    I am using Atlassian HTML Macro.. Kindly help me.


    1. I don't know of any way to make the Atlassian html macro work differently. Confluence ignores stuff within the header (except in preview mode). So either move the stuff into the body or use the html macro from HTML Plugin for Confluence with the parameters suggested.

  11. The ability to create content rich tech docs is the main reason we moved to Confluence, re: Dinoj, Tomas, deepak, saravanan ---when is this macro javascript only displaying on preview issue going to resolved? Is there an existing JIRA issue for this?

    1. It worked after a re load of the page for me - Please try the same

  12. Reload doesn't seem to cut it. maybe I'll try different browser versions/ I'm embedding a chart in JS, in the preview its in the right location. In the saved version its dumping it all the way at the bottom after the "Powered by Atlassian" that's also on this page. Not sure if I'm understanding correctly, does the issue for the edited page get permanently fixed after a single reload (until the next edit)? 

    UPDATE: Nevermind, error was in the javascript

  13. Anonymous

    Hello, is there a macro I can use so that my HTML links get rendered rather than displayed as source code? I have an HTML 5 help file stored in Subversion, which we host through JIRA. I want to add a link to Confluence so that people can pull up the HTML 5 home page of my help file, which contains a navigational link, etc. Unfortunately, no matter what I do, any kind of link I insert ends up displaying as source code, even if I click to open in new window or tab.

    Even better would be if I could display the content right inside of Confluence, like inside of an iframe or something like that. I really don't understand why this does not appear to be supported. This is a real functional gap in the product. You have support for the QA side of things, you have support for the development side of things, where is the support for the tech docs side of things?


  14. Anonymous

    Is there any idea why html does not render after save? I also see the html ok in preview, but it does not show after save,
    similarly as couple of guys before. We use the confluence version 5.1

  15. Make sure your HTML is well formed. If necessary, build up from something that works (or pair down until it works) so you know what is breaking it. 

  16. Hi Bob,

    While i am adding Html code to confluence 4.3 editor,it simply displaying HTML code. I want to add css to my content while building page

    i have also tried HTML macro inside my page:

    {html}<div style="background:red">some text</div>{html}

    But it displaying error while saving/previewing.

    Kindly help..


    1. I just saw this now. You have probably sorted it out already, but if for others it would be helpful if you mentioned what type of error you are seeing or if there is any error indiciated in the Confluence log. 

  17. Anonymous

    Is it possible to add a template variable inside the HTML macro?

    I want to insert some iFrames where the creator should choose the source.

    When selecting the panel macro you can use the "template-dropdown", but when the html macro is selected it is greyed out.

    And there is some minor bug: If you select the HTML macro header and then the textbox below the template dropdown is selectable and it seems you can use variables, but if you try to use the template, the variables won't be loaded correctly.


    Can you tell me how I can use variables in the HTML macro?

    Regards, Robin

  18. Can we use this macro for image mapping?

    1. By image mapping do you mean putting clickable hotspots over images?  I imagine you would be able to if you can code it in HTML.  You might want to ask your questions at Answers as someone in the community might have already tried this. 

      1. Yes. I have looked in there. It looks like there is a free plugin for image mapping, but the documentation is no longer there and many users say they are having issues with it. I have posed a question specifically about whether you can do this in the html macro. We shall see what they say (smile)

        1. I have once created such a page. (confluence 3.5 or 4) . It works but it is hard to create and hard to support without an authoring tool.

          1. I built an mapped image using and linked back to wiki pages we built.  It works when the source of the image points to the copy on . But if I change the source to point to our wiki path it doesn't work.  I don't know why but I'm thinking that it can't find the image "within". I'm going to ask IT to provide a place where it can upload the image to a public folder and see how that works. I'll report my findings.

            1. We use to map our images and are able to get it to work. Are you uploading the image as an attachment on the page, then taking the link path for the image itself rather than the page link? That is the image source link we use and have had no issues.

              The image link would look something like this:

              1. Yes, I took the wrong link. I've made the correction and everything is working. Thank you for the help.


  19. Bob Swift - The adding of the HTML plugin for Confluence allowed the rest of my page to be displayed, been working on this all day.  All I had was the HTML macro set up and it was only showing my HTML and not the rest of the items on my page.  You are a complete life savor.  Highly appreciate it.

  20. g m

    Why does confluence add <BR></BR> in my html tables?  I have an html table on my page and every time someone edits the table, confluence adds about 15 "<BR></BR>" to each row.  How can I get it to stop doing that?  Thanks

  21. Does this work in Confluence OnDemand? 

    1. Hi John,

      Unfortunately, for security reasons, there's no html macro of Cloud/OnDemand.

  22. Hi, I have tried to link to an anchor which is located in different page by using a HTML macro:

    Story : 

    Page A: there is an anchor called "bottom"

    In Page B, I want to link to the bottom anchor located in Page A and open Page A in a new tab and thus i use below HTML macro:

    <a href="Page A#bottom" target="_blank">Click to open Page A bottom in a new tab</a>



    This html does NOT work now (it works before!). It does open the Page A in a new tab, but it has not direct to the bottom of Page A. 


    Appreciate for your kind help (smile)

    1. Hi Iria,

      The link you need is <a href="Page A#PageA-bottom" target="_blank">Click to open Page A bottom in a new tab</a>

  23. Thanks Giles Brunning [Atlassian Technical Writer] (smile)

    I change the URL format as you suggested (Page name#pagename-anchorname) and it works now!

    Seems that: after the # sign, we should eliminate any space even the page name or the anchor name containing the space. Am I right ?



  24. Hi Giles Brunning [Atlassian Technical Writer], one more question:

    I want to cross reference among pages, say, there is link in Page B which will direct me to Page A when I click it. So in Page B, I use below HTML macro: 

    <a href="Page A" target="_blank">Direct me to Page A</a>


    FYI: in some pages, the above html works. However, in some other pages, it will return me a " Page Not Found" error and I need to use the exact URL of that page instead. 

    Can't I use the Page name as a URL? 

    Thank you in advance:)

    1. Hi Iria,

      It works for me when I test it, but you may need to check with support on specific use cases.

      1. Just test again, and the case happens by chance, so wierd...

        By the way, thank you so much:)

  25. I go to "Add Ons", then I pick "system", and I search for "HTML Macro".  

    This does not appear as an option in my system admin.  Why cannot I not see this Macro?  

    The documentation clearly states that this works for Confluence Cloud. 



    1. The HMTL macro has never been available for Cloud. See HTML Macro.

  26. The {html} macro is slightly broken if you enter it using the "just type the curly brackets" method. Eg., if I type {code}, a code block pops up. But if I type {html} I get a wiki markup block with the text string {html} inside.

    In fact, it's broken in this comment editor - it just happened as I typed the second instance of {html} on the previous line. 

    The workaround is to NOT type the closing } curly bracket but (*deep sigh*) lift your hand off the keyboard, go for the mouse and select HTML from the pop-up menu. 



    1. I didn't know that behavior was macro specific. I have just learned to key down to select before enter - really annoying behavior though.

      1. I wondered if it had anything to do with it being switched off by default ... that somehow "wiki markup" gets activated before the system has a chance to check if the html macro is enabled. 

    2. Hi Kathleen, does sound like something odd is happening with the autocomplete for that macro.  (You wont be able to try it out in this site, as we have that macro completely disabled).  

      The best way to get this looked at is to raise a bug about it. 

      1. Thanks, Rachel.  CONF-36774 - Entering HTML macro activates a wiki markup block Open  created.