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 Popular Labels macro displays the most popular labels used throughout your Confluence site or within a space. A popular label is a label that has been added to many pages. 

Using the Popular Labels Macro

To add the Popular Labels 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.

Parameters

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter

Default

Description

Number of Labels to Display
(count

100

Specifies the total number of labels to display in the heatmap.

Restrict Labels to this Space Key
(spaceKey

none

Restricts the list of popular labels to the specified space.

Style of Labels
(style

list

  • list – displays the popular labels as a bulleted list, ordered by popularity (highest first).
  • heatmap – displays the popular labels using different font sizes for each label depending on the label's popularity, ordered by label names.

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: popular-labels

Macro body: None.

Storage format example

Wikimarkup example

32 Comments

  1. This macro is working fine and displaying popular labels for the space I'm working with, but when you click one of the labels, the results show matches from all spaces the user can access -- how can I get the results to show only matches for the label within the current space?

    1. Hello jamiep77,

      Unfortunately, it's currently not possible to restrict the results of this macro to those restricted by its spaceKey parameter.

      However, this issue has already been raised in CONF-9149 and you can vote on it to increase its chances of being fixed in a future version.

      Best regards,

      Giles Gaskell
      Technical Writer
      ggaskell@atlassian.com
      ATLASSIAN - http://www.atlassian.com

      1. Thank you so much for the info -- I've voted on CONF-9149.

  2. I have modified the Popular Labels macro a bit since the standard version didn't fit my needs. The patched version supports customizing using CSS and sorting by label name and rank. You can download it here: Popular Labels Macro Tutorial.

    1. Nice one Arne, I'm looking for a way to change the background colour to transparent or white, your version looks like it might fit the bill nicely (smile)

      I was trying to simply use the style against the site, however all the styling on the heatmap is at the element level which can't be overridden.

  3. In Confluence 2.10.2, this macro does not seem to order by name, even if I use "style=heatmap" as indicated above.  It orders by popularity instead.  How can I order by name?

    1. Hi Craig,

      This is because of the existing bug, http://jira.atlassian.com/browse/CONF-13594, in which the ordering by name does not work without the spaceKey parameter. The "heatmap" style will order by popularity if spaceKey parameter is used.

      {popular-labels:style=heatmap|count=20|spaceKey=DOC} 
      

      In your scenario, are you trying to get the popular labels for the entire Confluence instance or just a space? If it is just a space, then putting the spaceKey parameter will solve it. Unfortunately, if it is a global popular labels you are aftering, we need to wait CONF-13594 to be resolved.

      sorry for any inconvenience caused,
      Henry CL Tiong

      1. Thank you Henry.  So, my next question is can a variable for spaceKey be used so the macro is still usable in a global template?  If not, is there another more usable heat map macro or plugin for labels?   Thanks in advance!

        Edit: I should clarify that I am looking for space-specific labels, but would like to use the macro in a global template.

        1. Hi Craig,

          You might want to create a user macro that can supply the current space key to the {popular-labels} macro:

          1. Create a user macro
            • Macro name: popular-heatmap
            • Untick "Macro has a body"
            • Output: Macro generates wiki markup
            • Template:
          2. Create a global template that calls the {popular-heatmap} macro we have just created.

          Now, the macro displays space-specific labels. Hope that helps!

          Cheers,
          Azwandi

  4. Anonymous

    Is it possible to restrict the user to view only those labels in space that the user has access to?

    1. Hi,

      As far as I know, I have tested it in Confluence 2.10.3 and Confluence 3.0. Unfortunately, the feature requested is not available yet. However, you might want to raise an improvement request in JIRA:

      Hope that helps,
      Zed

  5. Anonymous

    I'd like to list all spaces having with a specific team label. My goal is to display clusters of spaces grouped by team-lables. I've looked for space-specific macros but none provided me with a filter for team-lables. Any idea?

    Thx in adavance

    GuL

    1. Hi GuL,

      I think this is achievable by using the reporting plugin. Here is a sample code that works for me:

      Hope this helps.

      Cheers
      JSashi

      1. Anonymous

        JSashi

        great! Exactly what I was looking for!

        GuL

        1. Glad it worked for you, GuL!

          Cheers
          JSashi

  6. Anonymous

    Hi,

    We have lots of pages labelled rss_ that I dont want to appear in a cloud,  so is there a way to exclude certain labels in a space?

    1. Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at http://jira.atlassian.com. and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page

      Cheers
      JSashi

  7. Anonymous

    Hi,

    do you guys know a way to display a tag cloud in confluence with a time restriction of the tags - let's say a tag cloud that displays the most popular labels of the last month? The most popular tags in our wiki don't change too often, so it's a bit boring to always display the same labels.

    Any help is greatly appreciated!

    1. Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at http://jira.atlassian.com. and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page.

      You could also get more help in our Atlassian Answers.

      Cheers
      JSashi

  8. Anonymous

    Hi ,

    Can we make certain pages specific rather than complete space?

    Neha

  9. Anonymous

    Hi,

    I meant labels specific to certain pages rather than space.

    Neha

    1. Hi

      I meant labels specific to certain pages rather than space.

      I have a mere suggestion, you might want to try the Page Family Tag Cloud. Hopefully this plugin will satisfy some of your requirement.

      Hope that helps.
      Best rgds,
      Zed

  10. Anonymous

    Is it possible to add a narrow heatmap in line with (ie as a section of) the left hand menu?

    I have tried a few options in the 'Navigation' page and failed (popular labels did appear as menu line items). In heat-map form, I only seem to get the panel spanning the full page.

    Thanks in advance for any advice

    Jeremy

  11. Hi,

    Is it possible to exclude certain labels?

    For example I've created a blog using confluence but in order for the post to appear they all have to use a certain label. I'd like to exclude this lablel from the heatmap.

    Thanks

    James

    1. Hi James,

      I am afraid currently it is not possible to exclude certain labels using popular labels macro. Feel free to raise an improvement request at http://studio.plugins.atlassian.com. And describe in detail how you require this improvement to work. Please add yourself as a watcher for this improvement and add your own comments to this improvement request.

      Meanwhile, you can do that by using Tag Cloud Macro plugin along with excludePrefix or excludePostfix paramater.
      For example, if you want to display the most popular labels (excluding "book" and "cat") using Tag Cloud Macro plugin, you can write a macro like this:

      Please take note that you may need to read its documentation here for further usage.

      Hope that helps (smile).
      Regards,
      Husein Alatas

      1. Hussein,

        Is there a difference between the Tag Cloud Macro and the Page Family Tag Cloud? we have the latter installed and I'm wondering whether we could use this to exclude certain labels?

        Thanks

        James

        1. Hi,

          Based on the documentation of Page Family Tag Cloud, it looks like it doesn't have such parameter to exclude certain labels. And also please take note that currently it's not supported in Confluence 3.1.x above.

          To know more on the differences, you can read the documentation of Page Family Tag Cloud and Tag Cloud Macro.

          Regards,
          Husein Alatas

  12. How can I use spaceKey=current in this macro? If I use this in a template or a sidebar I'd like it to populate with only data from the current space.

  13. Hi,

    What determines the popularity of a label--the number of times it appears or the number of times users click on the label?

    Thanks!
    Andrea

  14. I installed 4.0-rc7 and the popular labels macro showed all labels in a list fashion even though I choose the heatmap style. Those labels are still shown in different font sizes based on their popularities but being rendered in a list rather than a tag cloud wastes screen real estate. Can this be changed back to tag cloud display? Thanks.

    1. It's the same in full retail 4.0 version (as you can see in one of the first comments on this page). Heat map style is not working properly yet (sad)

  15. Anonymous

    Hi, would also like to have the "heatmap" style working instead of a list. With the conversion to 4.0 all popular labels are listed.

    The heatmap was a nice visible tag on the main pages.