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 Navigation Map macro displays a navigable map of the pages tagged with a given label.

To add the Navigation Map 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 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).






Specify the label associated with the pages you want to show in the navigation map.

This parameter is unnamed in storage format and wikimarkup.

Map Title


Specify a title for the navigation map.

Number of Cells Per Row



Specify the number of cells in a row

Cell Width (Pixels)

90 px

Specify the cell width

Cell Height (Pixels)

60 px

Specify the cell height

Navigation Map Theme
(theme )


Define a theme for the navmap.

If you want to create your own navmap 'look and feel' (for example, one with rounded corners), you need to add a customised navmap macro theme file to the WEB-INF/classes/templates/macros directory. The file name convention to use is navmap-mytheme.vm. Use the name of your choice for the mytheme part of the file name, which is also the value you use for this parameter. Hence, if your theme was called navmap-roundededges.vm, use the value of roundededges for this parameter.

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: navmap

Macro body: None.



  • No labels


  1. The ability to pull in all pages with a given label from anywhere in the system is great.  But, a gotcha with this macro is that it is not restrictable to the current, or a given set of spaces.  Unless great care is taken with labels (I don't see users prefixing their labels with a spacekey!) the result is a grouping of similar but totally unrelated content, which isn't helpful.

    1. Good point, but it's a simple workaround just by assigning a specified label and making aware that your specified label only has this use. For example, name your label as "Navmaponlylabel" or something to that effect.

      Use this in combination with the Label Management Plugin to batch apply labels!

  2. I've just updated to 2.6.0. The WEB-INF/classes/templates/macros directory is not in that version. I created it and put the navmap-<mytheme>.vm into it. That works, but is that the right way for the future ?

    1. Hi Reinhard,

      I presumed you meant to say that, you have created a directory structure of WEB-INF/classes/templates/macros in your Confluence instance and place the customized navmap file in the defined directory. If this is the case, the workaround should work to the Confluence instance. For you information, the navmap-mytheme.vm file is now available in the confluence-2.6.0.jar file located in the <confluence-install>/WEB-INF/lib directory. Hence, another workaround would be to extract the jar file and to place the customized navmap file into the same directory of where the navmap-default.vm file is. Please ensure that you have re-JAR the extracted files and re-locate the jar file into the correct directory after performing any modification to the jar file. It is also advisable to always make a backup of confluence-2.6.0.jar before performing any customizations.

      Choy Li

      1. Hi Choy Li,

        placing the navmap-mytheme.vm in a directory WEB-INF/classes/templates/macros works as in the 2.5.x version, thanks so far.
        But: putting any customizations in the WEB-INF directory (or anywhere else in the installation directory) is always annoying (sad), I would expect such thinks somewhere in confluence home directory that is specified in the file.


        1. Hi Reinhard,

          Indeed, the files that are being stored in the Confluence home directory contains data that work with the Confluence database. Perhaps, you maybe interested to look at the Confluence home directory contents as listed in the following documentation:

          Hence, the velocity(.vm) files should be located in a proper directory as mentioned in the above directory in order to make it work to the Confluence instance.

          Choy Li

  3. Hi,

    Thanks for the navmap macro.

    Is it possible to restrict the display of cells having a given label to a specific space?

    Best wishes,


    1. Hi Nicolas,

      Unfortunately this can't be done at the moment.


      1. Too bad, because if you use the content publishing plugin to duplicate a subset of a private space to public one, the navmap macro will duplicate everything.

  4. Is there a way to remove those gray flashing dots that appear between the cells? They're driving me crazy!

    :-D, sorry, couldn't resist (wink)

    1. Hi Roberto,

      Sorry to say that I could not find any workaround that can be used to fulfill your requirement. To my understanding, this is the behavior of the Navmap Macro. Perhaps, you may want to raise an improvement request in the following JIRA Issue Tracker:

      Choy Li

    2. Anonymous

      Actually the grey flashing dots are not there at all.  They're an optical illusion - there's nothing you can do about them!

      Clive Washington, AstraZeneca.

  5. Hi,

    It would be very nice to parameterize colour, i.e.:

    • foreground
    • background
    • border



    1. Hi Martin,

      Thanks for the suggestion. However, this feature is not provided currently. You may want to raise an improvement request at here to truly reflect the importance of this improvement.

      Choy Li

  6. Hi,

    Is there a way to display the space description from each page along with the lables?



    1. Hi Anitha,

      Unfortunately, Confluence does not provide this feature and there is no macro/plugin that i am aware of to fulfill your requirement. Perhaps, you may want to give a try to search for other plugins in our Confluence Extension space which might meet your requirement.

      Alternatively, you may want to create a feature request at our JIRA Issue Tracker to truly reflect your requirement.

      Choy Li

  7. Is there a way to reverse the order in which boxes appear?  I can do it by carefully selecting the names of the children, but that is a little cumbersome.

    1. Hi Edgardo,

      Please create an improvement request at the JIRA Issue Tracker to truly reflect your requirement.

      Choy Li

  8. Anonymous

    Hi to all,

    we are working with confluence 2.7.3 and make much use of the navmap macro.
    Now we wanted to export the wiki to html, but it seems that the links for the navmap were not handled relative, because the links tried to open the absolute wiki path.
    Do anybody have any solution on this issue?

    Many Thanks


    1. Hi Andreas,

      This appears to be a known issue when a page with NavMap macro being exported to HTML. There is a discussion regarding problems between page with NavMap exported to HTML format being tracked here:

      Please add comment in the issue raised to truly reflect the problem that you are seeing. Also, feel free to cast your vote to increase its popularity and add yourself as a watcher for future updates.


  9. You can track the issue regarding limiting the Nav map to defined space here:

  10. Anonymous


    is it possible to change the layout by using css and the html-macro?

    And a second question: Can i add 2 Labels to the macro as "or"?

    1. Hi,

      is it possible to change the layout by using css and the html-macro?

      Yes this is possible, provided that you know which CSS class is related to this change.There are few options to do this:

      1. Embedding the CSS style sheet inside your HTML macro. Here is an example to change the background colour to yellow:
      2. Using the Stylesheet function to edit CSS code.
      3. Using the Custom HTML in Administration Console. Please bear in mind that these changes will modify all the pages in Confluence.
      4. Changing the JAR file of the Confluence Advanced Macros plugin, which is located in <confluence-install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup/

      Can I add 2 Labels to the macro as "or"?

      Unfortunately this will not work, because the {navmap} macro will only grab the first label supplied to it. If you are keen to have this feature, please raise an improvement request at

      Hope that helps!


  11. For themes, things seem to have changed for 2.10.2 (or earlier). If I do a custom theme in WEB-INF/classes/templates/macros as suggested I get no navmap and an error in atlassian-confluence.log stating it's looking for the .vm in a different place.

    The new location for theme .vm files is now WEB-INF/classes/com/atlassian/confluence/plugins/macros/advanced. Once I'd dropped my custom theme in there everything worked fine.

  12. Anonymous

    Hi !

    Can someone tell me how I can center the block "navmap" in my page. I didn't find a answer in the Internet :-(

    Many thanks !

    1. Hi,

      As far as I know, the feature requested is not available yet. However, you might want to raise an improvement request in JIRA:

      In the mean time, you might want to try the html macro. I have provided a sample code as example:

      Hope that helps.
      Best rgds,

  13. Does anyone know if you can add multiple labels for this macro?  Having problems with more than one.

    Thanks, Mark

  14. It is very handy to get a tooltip showing up excerpt text when mouse hovering over navmap cells.  How about




    1. Hi Radu,

      If you are keen to have this, feel free to raise a feature request at Also, learn how our development team chooses what to implement in future releases.


  15. Does anyone know where I can find the latest source code for the navmap macro? Specifically I would like to view/edit the navmap-default.vm file so I can customize the look and feel. I couldn't find this information from reading the comments above.



  16. Anonymous

    Is it possible to add multiple labels to this macro?

    1. Anonymous

      Was there a solution to this? 

  17. Anonymous

    Documented path for custom theme (WEB-INF/classes/templates/macros) is invalid 

    I found this path /atlassian/confluence/plugins/macros/advanced/ in Navmap Macro source code and it is work great!
    1. Anonymous

      For 4.3.2 it looks like the navmap templates now need to be put in the WEB-INF/com/atlassian/confluence/plugins/macros/advanced directory to be picked up by the macro.

  18. Anonymous

    After the update on version 4.2.1 the macros also contains/shows deleted pages! Can this be disabled?

    1. Anonymous

      I am having this issue as well, does anyone know of a fix?



      1. Anonymous

        Does anyone know if version 4.3 fixes this issue?


    2. Hello,
      Thanks for pointing this issue out for us!  I have filed the following bug report with development.

      CONF-26706 - Navigation Map Macro Does Not Remove Deleted Pages Resolved

      There are two workarounds as well listed with the report so please have a look.

      Andrew Campbell,
      Atlassian Support, San Francisco 

      1. Anonymous

        Thanks, Workaround 2 worked for us.


  19. Anonymous

    Why can I not determine (or influence) the way in which the navmag "blocks" are shown ? Now these blocks are shown in alphabetical order only. It would be much more efficient for me and the users using the Confluence product if I could shown them the most important block first, the lesser important last...

    example : if you have 10 blocks with navmag on a page : they will be shown as follows :



    It will take the user some time to read, to focus and to locate that vital is on the last, best practice somewhere in the middle...while I as an administrator (not to speak about the users) want the viewer to focus immediately on the most important one to be read : the first three or five ones....VITAL, IMPORTANT TO KNOW, BEST PRACTICE, COOL, TIPS & TRICKS and then on a 2nd line Less Important, Average, Mediocre, Absolutely irrelevant etctera

    I could "bypass" it by re-naming the blocks by adding a number to force the blocks in another hierarchy like e.g. 1VITAL, 2BEST PRACTICE, 3COOL but that looks cumbersome to everyone...


    Thanks in advance !

  20. Great marco, but having some issues:

    CellHeight & CellWidth are not working in Confluence 5.4.1 and 5.4.3. Other versions not tested. Cells are always displayed using default values.

    Example: Setting Width & Height to 120px in macro config.


    Generated HTML is always using defaults:

    Navigation Map HTML

    Even when previewing the macro, cell height & width are not respected.




    1. Thank you for bringing this to our attention. We have created a bug report in regards to this issue: CONF-33001

      1. Thx,

        I didn't try setting the values without adding 'px'. Just entering the values without a suffix solved my problem.


  21. When using the Navigation Map Macro in our on demand environment I keep getting the error:

    "Error rendering macro 'navmap' : com.atlassian.renderer.v2.macro.MacroException: You must specify a labelName."

    I am using a valid LabelName that is used (kb-how-to-article)

    1. Hi Eric, I have just tried this out in OnDemand, and couldn't replicate the problem.  If you contact support they will help you troubleshoot the problem.  

  22. When we upgraded to version 5, the space-specific stylesheet that worked perfectly in version 3.5.x is now ignored. Here is an example of CSS that previously worked, but now does not.  Is it no longer possible to format a navmap using local CSS?

    a.navMapCell, a.navMapCell:link, a.navMapCell:visited 
     a.navMapCell:link { 
     color: #000000
    a.navMapCell:visited { 
        text-decoration: none; 
        color: #FF0000; 


    1. Hi Kathleen, to be honest I don't know. This might be a good question to ask at Answers, as someone else may have solved this.  Confluence 5 had some very big changes to look and feel so its possible that the classes etc are different now. 

      1. Good idea, will do that.