Navigation Map Macro

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 Autocomplete for links, files, macros and mentions.

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).

Parameter

Default

Description

Label

none

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
(title

none

Specify a title for the navigation map.

Number of Cells Per Row

(wrapAfter)

5

Specify the number of cells in a row

Cell Width (Pixels)
(cellWidth

90 px

Specify the cell width

Cell Height (Pixels)
(cellHeight

60 px

Specify the cell height

Navigation Map Theme
(theme )

Confluence

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.

Was this helpful?

Thanks for your feedback!

49 Archived comments

  1. User avatar

    Andy Brook [The Plugin People]

    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.

    31 Aug 2007
    1. User avatar

      Eugene Wang

      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!

      14 Feb 2009
  2. User avatar

    Reinhard Jöhnk

    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 ?

    08 Oct 2007
    1. User avatar

      Choy Li Tham

      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.

      Regards,
      Choy Li

      09 Oct 2007
      1. User avatar

        Reinhard Jöhnk

        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 confluence_init.properties file.

        Reqards,
        Reinhard

        09 Oct 2007
        1. User avatar

          Choy Li Tham

          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.

          Regards,
          Choy Li

          10 Oct 2007
  3. User avatar

    Nicolas Bertrand

    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,

    Nic

    18 Oct 2007
    1. User avatar

      Mei Yan Chan

      Hi Nicolas,

      Unfortunately this can't be done at the moment.

      Regards,
      Mei

      19 Oct 2007
      1. User avatar

        Robert Gosselin

        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.

        07 Feb 2008
  4. User avatar

    Roberto Dominguez

    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)

    07 Feb 2008
    1. User avatar

      Choy Li Tham

      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:

      Regards,
      Choy Li

      11 Feb 2008
    1. User avatar

      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.

      17 Jun 2010
  5. User avatar

    Martin Pieter Misseyer

    Hi,

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

    • foreground
    • background
    • border

    Greetings,

    Martin

    24 Feb 2008
    1. User avatar

      Choy Li Tham

      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.

      Regards,
      Choy Li

      25 Feb 2008
  6. User avatar

    Anitha Raghavan

    Hi,

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

    Thanks,

    Anitha

    24 Mar 2008
    1. User avatar

      Choy Li Tham

      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.

      Regards,
      Choy Li

      25 Mar 2008
  7. User avatar

    Edgardo Luzcando

    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.

    27 Mar 2008
    1. User avatar

      Choy Li Tham

      Hi Edgardo,

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

      Regards,
      Choy Li

      28 Mar 2008
  8. User avatar

    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

    Andreas

    10 Apr 2008
    1. User avatar

      Tony Cheah Tong Nyee

      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.

      Cheers,
      Tony

      11 Apr 2008
  9. User avatar

    George Thomas

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

    10 Jul 2008
  10. User avatar

    Anonymous

    Hi,

    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"?

    17 Feb 2009
    1. User avatar

      Komathi Krishnan [Atlassian]

      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/atlassian-bundled-plugins.zip.

      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 http://jira.atlassian.com.

      Hope that helps!

      Cheers
      Komathi

      03 Mar 2009
  11. User avatar

    Liam Jones

    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.

    02 Mar 2009
  12. User avatar

    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 !

    27 May 2009
    1. User avatar

      Zed Yap [Atlassian]

      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,
      Zed

      28 May 2009
  13. User avatar

    Mark Doty

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

    Thanks, Mark

    23 Sep 2009
  14. User avatar

    Radu Marian

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

    ?

    TIA,

    Radu

    30 Jun 2010
    1. User avatar

      Azwandi Aris [Atlassian]

      Hi Radu,

      If you are keen to have this, feel free to raise a feature request at https://studio.plugins.atlassian.com/browse/ADVMACROS. Also, learn how our development team chooses what to implement in future releases.

      Cheers,
      Azwandi

      28 Jul 2010
  15. User avatar

    Greg Miller

    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.

    Thanks,

    -Greg

    22 Oct 2010
  16. User avatar

    Anonymous

    Is it possible to add multiple labels to this macro?

    10 May 2011
    1. User avatar

      Anonymous

      Was there a solution to this? 

      29 Aug 2013
  17. User avatar

    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!
    23 Mar 2012
    1. User avatar

      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.

      23 Jan 2013
  18. User avatar

    Anonymous

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

    27 Apr 2012
    1. User avatar

      Anonymous

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

      Thanks

       

      27 Aug 2012
      1. User avatar

        Anonymous

        Does anyone know if version 4.3 fixes this issue?

        Thanks

        06 Sep 2012
    1. User avatar

      Andrew Campbell [Atlassian]

      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.

      Cheers,
      Andrew Campbell,
      Atlassian Support, San Francisco 

      24 Sep 2012
      1. User avatar

        Anonymous

        Thanks, Workaround 2 worked for us.

        Josh

        02 Oct 2012
  19. User avatar

    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 :

    AVERAGE, ABSOLUTELY IRRELEVANT, BEST PRACTICE, COOL, IMPORTANT TO KNOW

    MEDIOCRE, LOSERS, LESS IMPORANT, TIPS & TRICKS, VITAL

    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 !

    12 May 2012
  20. User avatar

    Jan-Peter Rusch

    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.

     

     

     

    19 Feb 2014
    1. User avatar

      Septa Cahyadiputra [Atlassian]

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

      20 Mar 2014
      1. User avatar

        Jan-Peter Rusch

        Thx,

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

        Jan

        20 Mar 2014
  21. User avatar

    Eric Paul Verheugen

    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)

    12 May 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      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.  

      14 May 2014
  22. User avatar

    Kathleen James

    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 
        background-color:yellow; 
     
     a.navMapCell:link { 
     color: #000000
    a.navMapCell:visited { 
        text-decoration: none; 
        color: #FF0000; 

     

    21 Aug 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      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. 

      21 Aug 2014
      1. User avatar

        Kathleen James

        Good idea, will do that.

         

        28 Aug 2014
Powered by Confluence and Scroll Viewport