Skip to end of metadata
Go to start of metadata

This macrodefines where the page/news comments, if enabled, will be shownwithin the theme layout.

Users can toggle the display of this macro using the link output from the menulink macro with a destination of comments.



This macro can only be used inside panels within the theme configuration screen. You cannot use it in pages or news articles, etc.


This macro has no parameters.


Basic Use

Add the macro to any panel in theme configuration to display the comments in that panel:


CSS Customisation

To follow.

Hints and Tips

A common requirement is to only show comments to users in a specific group such as content authors. This is really handy because it allows content authors to discuss edits to pages, etc., using comments without cluttering up pages for normal visitors:


We've used the show-to macro and set it up so that the comments are only shown to people in a "content-authors" user group (this group doesn't exist by default so you'd have to create it or use a different group).

Ideally you should also include the "confluence-administrators" group (which all administrators are added to automatically on Confluence installations that don't use LDAP):


(warning) Warning:
Remember that comments are searchable - even if they aren't displayed on pages, they may still appear in search results.

If you want a more flexible way of choosing which pages display comments, you can use the builder-show macro in such a way as to only show comments when a specific label is added to the page, etc.


That would only show the comments block on pages that have a "showcomments" label.

Frequently Asked Questions

Why are my comments not shown?


First of all, check that the following wiki notation is included in one of the theme panels:


If it's not, then add it

Also, check that the panel which contains the macro is enabled - if the panel isn't shown, it's contents aren't shown.

If you have hidden comments (eg. using the "Hide Comments" link), then they will not be shown on any pages until you re-display them again. There are a few ways you can display comments...

The best way is to use the menulink macro to display a link or menuitem that allows users to show/hide comments

Unknown macro: {footnote}

This link is included as default on the View menu for pages that have comments.


{compound-menuitem:comments|flat=true|caption=Show comments (%count%)}
Unknown macro: {display-footnotes}

Which displays:

Unknown macro: {compound-menuitem}

We've wrapped the link in the menuitem macro so that pages which do not have comments will not display an inactive link.

Another alternative is to allow the user to post new comments

Unknown macro: {footnote}

If the user has sufficient privileges, they'll see this link on the Edit > New menu


{compound-menuitem:newcomment|flat=true|caption=Post a comment}

The disadvantage of this second approach is that it doesn't let the user know if there are any existing comments until they click the link. Also, if the user does not have permission to add comments, they won't see the link.

A third approach is to include the showComments=true setting on the page URL. For example, the URL to this page is:

You would change that to:

Anyone accessing this link would automatically get the display of comments switched on, regardless of what previous settings they had used.

Another approach is to set the 'force comments' flag in the options tab of the layout


  1. Unknown User (gfraser)

    Example comment

  2. Anonymous

    Hey Guy,

    I was wondering if there is a way to add comments in a table, so that the comments can be matched to a specific row or point. Thanks

    1. Unknown User (gfraser)

      Not currently. We're working on a new plugin called "Bubbles" which will likely have an Adaptavist replacement for the standard Confluence comments block at some stage, however it's not likely to be released prior to March 2007.

  3. Anonymous

    Hi Guy,

    Can comments be sorted with the newest comments at the top of the list rather thatn the bottom?

    1. Unknown User (gfraser)

      Not currently - our macro merely encapsulates the Confluence comments fuctionality at present, although we will likely create our own version of the comments system at some stage.

  4. Unknown User (mbovett)

    When you're editing a page, there's a "Comment" field. The Atlassian site (I think it was their site) has a "VIEW COMMENT" option at the top of the page which lets users view the last comment that was left by an editor... is there any way to make this appear in the page header with ThemeBuilder?

    1. Unknown User (gfraser)

      You can use the menulink macro with a location of "comments", eg:


      EDIT: Ah, I've just realised what you are referring to - the "edit comment", eg. when editing a page a comment can be added to that version to say what was done, etc. You can use the version-history macro but I agree it would be nice if there was the "View Comment" feature as well which is less obtrusive. I'll add a ticket to our tracker to see if that can be implemented in a future release.

      1. Unknown User (mattbovett)

        Ahh, cool! Thanks Guy! This version-history macro is pretty cool though. I think I'll make use of it.

  5. Unknown User (

    Hi Guy;

    Very basic question. We are using themebuilder, and trying to get the ability to reply to a specific comment. Right now we don't have the ability to "Reply to this". Is this a macro? How do I enable this important feature in theme builder?

    Thanks in advance,


    1. Unknown User (gfraser)

      I think you need to enable "Threaded Comments" in Administration > General Configuration.

      1. Unknown User (

        worked like a champ Guy. Many thanks.

        I have version 2.0.9 of Theme Builder I have?

        When is Version 3.0 GA??

        There's a great site using themebuilder:, and I see their rating system. If you could have a look, is their rating maceo something that's generically available?

        1. Unknown User (gfraser)

          We will be announcing the GA of 3.0 in the News tab of this space. You can find the current version of the plugin you have installed via the Plugin Manager.

          The ratings on are a custom component I believe, written by Stephan Janssen of the Belgian Java User Group.

  6. Unknown User (


    I have been working on a new theme for our spaces... I have now gotten the tabs to work (thanks to you all) but my builder-comments have disappeared or will not show up. I have the footnote visible and I even placed some text in the same area to make sure I did not have the text color set to white or something weird. I then migrated to another space where I have not applied this new theme.. and the builder-comments work. So do you know of any quirks with the side tab theme? And I did not understand the above section about "showComments=true". Can you maybe point me in the correct direction?

    1. Unknown User (amoran)

      ensure that the 'comments' menulink is in your menus and ensure that the checkbox next to it is ticked .. alternately ensure that the 'force show comments' checkbox in the options tab of your layout is checked.

      Unless either of these are set to true then comments will be hidden.

      1. Unknown User (skoch)

        I have Themebuilder 2.0.9 site with Confluence v 2.5.7.
        I am using the builder-comments macro in the footnotes section. How do I force comments to be shown to users and hide the hide comments link when comments section is displayed? With our theme design, users do not have menus visible to them. I did not find the force show comments checkbox option in Builder 2.

  7. Unknown User (

    I'm having a similar problem to Gina's above. I have the builder-comments macro in the footnotes panel (which is enabled). If I use "force show comments" in the options tab, they show up there, and the "Hide comments" link of course doesn't do anything.

    If I disable "force show comments" and try to use the default comments menulink item in the View menu, the checkbox next to "Show comments" is never ticked, and the comments are never displayed.

    If I manually append showComments=true to the page URL, the comments are not displayed.

    I'm using TB 3.0.0 (the latest I think), and confl. 2.7.

  8. Unknown User (

    Hi Jessica,

    I finally resolved this issue by recreating a theme where the comments were working and then adding the new theme settings that I created one by one.
    I found that as long as I did not select the option:
    Remove Home/Orphan Page (3rd item) from Breadcrumb Trail....
    Then everything seemed to work.

    As soon as I selected that option, then the comments would not work. Even if I unselected the option... I had to create from scratch again to make the comments work.

    1. Unknown User (gfraser)

      That's really weird - could you create a ticket on and upload your theme config so we can take a look? The breadcrumb options shouldn't have any effect on the comments block :s

      1. Unknown User (

        So I just created a new theme based on the default theme, and didn't touch anything else. The comments are still broken as I outlined above. So I'm not sure how to follow your workaround since I can't seem to create a theme with functional comments to begin with.

        If I apply the default theme, comments work as expected...

        1. Unknown User (dudester)

          I have the same problem when using a custom layout. Has there been a solution to this problem?


  9. Unknown User (

    Same problem here. Using Confluence 2.7 and TB 3.0.1.
    Created my custom theme which differs very little from the default. I only changed the colors, removed the header, added some custom code to Menu panel content to display company logo and background:

    <!-- Banner -->
               <TABLE align=left cellSpacing=0 cellPadding=0 width=795 border=0>
                    <TD width=160><A 
                      href="/confluence"><IMG height=55 src="...." width=138 border=0></A></TD>
                    <TD width=620><IMG height=61 src="....." 
    <!-- End of Banner -->

    Now the comments section is not showing up unless I force comments in the Layout Manager.


    1. Unknown User (gfraser)

      I'm pretty sure Theme Builder 3.0.2 fixes that bug...

      1. Unknown User (

        Yes it does! Thanks, I didn't realize there was a newer version since I downloaded 3.0.1 a few days ago.

  10. Unknown User (ashdodia)

    When using

    {menuitem:flat=true}{menulink:comments}Show comments (%count%){menulink}{menuitem}

    and there are no comments in the page I get "Show comments (%count%)" instead of "Show comments (0)".

    Any idea how it can be solved?


  11. Unknown User (dmatsum)

    Is there a way to get the standard add comment icon to display with this macro? I tried preceding it with {menuicon:message_add}, but they appear on different lines and get separated when comments are added.

    It isn't a huge issue, but we are trying to keep the interface similar to the existing one when we transition to theme-builder.

    1. Unknown User (dmatsum)

      Covered via Support question.

  12. Unknown User (scayla)

    Hi Guy.

    I have two questions about this builder-comments macro :

    • On February 2007, 15th, in answer to the question "can comments be sorted in order to have the newest comments on top?", you said

      Not currently - our macro merely encapsulates the Confluence comments fuctionality at present, although we will likely create our own version of the comments system at some stage.

      Nowadays, would you answer the same ?
    • Is there a way to have all comments collapsed by default ? I can see that the builder-comments macro doesn't have any parameter...

    Thanks a lot for your answers.

    1. Unknown User (amoran)

      That is correct ... we do not expect to replace the confluence comments functionality within the builder plugin.

      The bubbles plugin on the other hand is looking at modifying the comments and page edit screens so that they can appear more like a forum, which could be useful to you ... however that process is some time away from being started.

      1. Unknown User (scayla)

        Thank you Alain for your fast answer.

        Did you answer to the "have all comments collapsed by default" question when talking about the bubbles plugin ?
        Looking inside my page, I can see that when clicking on "Collapse all", it appends the word "collapsed" in each comment's class, which, as a result, collapses the comments. I didn't see any javascript file nor function called when clicking on "Collapse all". Is there any function I can copy to have all comments collapsed when accessing a page ?


        1. Unknown User (amoran)

          Gotta love jQuery .. makes it really difficult for people to locate the code that they want to prod ... you want to be looking at the comments.js file, by the looks of things you need to execute the following code

              $('#comments-collapse').click(function() {
                  $('.comment:lt(10):not(.collapsed,.add,.reply,.edit)').each(function () {
                      onFinish: function () {
                  return false;

          However timing that to execute once the jQuery comments code has finished loading and setting itself up could be problematic ... you could try adding it to a user macro and then including it after the builder-comments macro.

  13. Unknown User (markane)

    I am using the

    Unknown macro: {compound-menuitem}

    macro as a navigation item and need comments to NOT be viewable by default. Is there a macro parameter to do this? Currently I have the following:

    {compound-menuitem:comments|caption=Show comments (%count%)}

    Some of my pages have many comments and I need those to be hidden when a new user views the page, but still have the option of displaying comments if (s)he chooses.


    1. Unknown User (amoran)

      Mmm ... not at the moment, however it's something we can look into for 3.4

  14. Unknown User (grmi64)

    Hi -

    Is there a way to simply adjust the formatted text?

    h3. {builder-comments}

    ...doesn't seem to work.



  15. Unknown User (

    I'm using Theme Builder 4.1.3 on Confluence 3.3 and attempting to use builder-comments along with builder-hide to hide comments from anonymous users.

    I have the macros set up in the footnotes, and they work. But the pages show the children and comments from the default Confluence install. Is there a way to force these built-ins to not show on the page?

    1. Unknown User (amoran)

      1. Unknown User (

        I actually use this exact code. But it shows one set of comments to anonymous users and 2 sets to logged-in users.

        1. Unknown User (amoran)

          Then you have another copy of the {builder-comments} macro in your layout somewhere, or you have edited a velocity file away from the standard implementation.

          Try switching off ALL of the panels and see if it still happens - if this is the case then someone has been editing your base install velocity - builder can do nothing about this, you should revert the file back to the version that came with your install.

          If switching all the panels off 'resolves' this then try switching the panels back on until it recurrs - you should then have located the panel with the extra macro & you can remove it.

  16. Unknown User (bng_goldenboy)

    How do I format the comments using CSS? Is it possible?

  17. Unknown User (martin-r)

    Had a question but found the answer. Sorry

    1. Unknown User (amoran)

      It's generally worth replying to your own comment instead of wiping out the content ... everyone else will now be wondering a) what your original comment was, and b) what the resolution you found was ... other people may end up making the same mistake & your information could be helpful to them (wink)

  18. Unknown User (exsiss)

    I have tried both the show-to and hide-from macros to hide comments but it always results in the page saying "Unknown-macro: /

    Unknown macro: {show-to}
    " (or hide-from). Are these macros no longer available?


    1. Unknown User (exsiss)

      I figured it out, you need to have the plugin "CustomWare Visibility Plugin" installed.

      1. Unknown User (amoran)

        How do you figure that? .. visibility does less than builder-show does & may not work in all situations (it's designed for use on pages & may cause you problems on global & search)

        1. Unknown User (exsiss)

          Well, I figured that because once I installed the plugin it worked.

          Comparing the two pages on builder-show and show-to the only differences seemed to be that one had more parameters (the only parameter I really needed was users and groups). However I couldn't get builder-show to work correctly (although it didn't say "unknown macro", it wasn't taking the if/thens into account), and I did with show-to.

          Now reading your comment it seems there is a big difference between the two and it might be worth figuring out why builder-show isn't working correctly.

          Also, rather than fumbling around I thought I'd ask about the possibility of a situation. I've come to figure it isn't possible but I thought I'd ask just in case. Say I want regular users to be able to comment on a page, but only admins can see all comments. It would be nice to also have it so regular users can see the comments they posted, but that the previous requirement is more important.

          I originally thought I could do this by using show-to/builder-show with the group set to admins (with the possibility of using something similar to @author to allow the user to see their own posts), but now I see this also hides the ability to add comments for regular users.

          All in all, is this possible?