TracNav: The navigation bar for Trac

The [[TracNav]] macro implements a fully customizable navigation bar for the Trac wiki engine. The contents of the navigation bar is a wiki page itself and can be edited like any other wiki page through the web interface. The navigation bar supports hierarchical ordering of topics. The design of TracNav mimics the design of the TracGuideToc that was originally supplied with Trac. The drawback of TracGuideToc is that it is not customizable without editing its source code and that it does not support hierarchical ordering.

A life example of TracNav can be seen on the right. Please use this navigation bar to learn more about TracNav.

If you just want to play around with TracNav, please use the SandBox!

Comment by cboos@… on Wed Mar 2 19:28:09 2005

Excellent idea!
-- CB

Comment by reinhard.brandstaedter at on Thu Jul 14 10:44:50 2005

Great stuff! But I'm wondering how to use multiple hierarchies in the navigation with links enabled. In your Nav: "See also" as heading "TracNav" as subheading with link-function "Overview" as subsubheading with link function

Is this possible? Everytime I add a child-link tocentry under a link this link is not displayed.


Comment by pellatt@… on Sat Jul 16 11:56:43 2005

I'd like to use this for making a few quick links to things like current milestones and reports, any chance of adding that functionality?


available since r3057, and also in Release 3.2 to the MacroBazaar
-- Thomas

Comment by christophe on Thu Aug 4 18:09:10 2005

ceci est un test, merci pour votre travail ;)

Comment by sewerson on Fri Aug 19 21:32:45 2005

TracNav always responds with Error: Macro TracNav(TOC) failed not all arguments converted during string formatting somehow buggy code

TracNav works with Trac >= version 0.9 since r3044 resp. Release 3 to the MacroBazaar
-- Thomas

Comment by anonymous on Mon Nov 21 19:56:18 2005

How about support for inline navigation?

Comment by jose@… on Thu Feb 9 09:05:07 2006

OK I give how do I download this? I click on the links and they show the code embedded in a webpage but no way to actually download the code

Comment by jose@cybergalvez on Thu Feb 9 09:15:22 2006

Sorry about the previous comment I figured it out

Comment by anonymous on Sun Feb 19 22:46:31 2006

I'd like to force TracNav to show the entire TOC in all cases, without collapsing or formatting some captions bold+black. Is there any way to do this?

You may try to remove the call to the filter_toc function. In line 218, replace

(found, filtered) = filter_toc(curpage, toc, 0)


(found, filtered) = (0, toc)

This will display the TOC alway fully expanded like in the TOC edit mode. If you now really do not like bold face for headings, you can experiment with the line 82 in wiki.css:

Try to add to

.wiki-toc.trac-nav h4 { margin: 0; padding: 0; }

the style you like for headings, e.g.

.wiki-toc.trac-nav h4 { margin: 0; padding: 0; font-weight: normal; }

I did not try this recipe myself, you might have to experiment a little. Regards,

Since r3088, TracNav knows the nocollapse argument, which prevents the TOC from being sorted or collapsed.

Comment by TomB on Fri Jun 9 14:29:19 2006

Hi together :)

My installation doesn't work as it should ;( I'm using version 0.8.1. I've downloaded the right package imho and followed the instructions on this site (

But it always says: Error: Macro TracNav(None) failed invalid syntax (, line 1)

Any suggestions? Many Thx!

The latest TracNav packages will not work with Trac 0.8. Either update Trac, or try one of the older versions, see log:trac/trunk/wiki-macros/

Comment by eliott on Mon Jul 17 10:10:33 2006

Is there a way to get the tracnav to show on the left side of a page, instead of the right?

Add something like .wiki-toc.trac-nav { float: left; margin: 0 .5em 0 0;} to the site_css.cs file of the templates directory of your project.

Comment by anonymous on Fri Aug 18 18:28:41 2006

I suggest to to use 'WikiStart' instead of an empty string as the second Parameter of the getValue call in the 'curpage = ...' line in the execute method. This allows for using a Link to the WikiStart page in the TOC and a Link without a page name will properly be identified as the WikiStart page. (Compare this to your javascript hack on your WikiStart page).

Done in [3106] resp. 3.92pre6. Thanks for suggesting it!

Comment by anonymous on Mon Aug 21 07:30:26 2006

I'm feeling a little stupid, but given that I'm just starting out with Trac I guess I'm entitled to that. ;)

How do I change the actual title text of the NavBar? The examples here don't have a title, but my basic installation has a large text 'TracNav menu' across the top, which is bigger than my menu and looks pretty weird.

Any help appreciated.

This sounds to me as if TracNav's stylesheet were missing. You have to set PYTHON_EGG_CACHE to a directory writable by the webserver. See

P.S.: It would be nice to have a repository for style tricks, i.e. how to get the NavBar as a full menu on the left, instead of a box like in Feb 19 comment above.

Comment by Paulo on Wed Aug 23 18:00:35 2006

Is there any available version for Python 2.3?

No, because we don't have Python 2.3 here. But you can easily build it yourself from the zipfile provided on the download page.

Comment by jwilliams on Fri Sep 15 06:40:56 2006

Prev/Next navigation footer for TracNav?

How about a [[TracNavFooter(TOC)]] macro, that renders a page-specific navigation bar to the previous, next and "parent" page in the heirarchy defined by the TOC?

Users adding this macro to the bottom (or top) of each wiki page would give a nice ability for sequential navigation.

This info is already parsed out by the TracNav macro, would just be slightly different way of rendering it. My python/trac hacking skills are zero else I would attempt it myself.

See #262.

Comment by jwilliams on Thu Sep 21 04:46:08 2006

Macro to render an entire TOC as one page

Another idea, how about a Macro that takes a TOC page, and collates all of the content rendering it as a single page?

This, combined with the PDF renderer plugin, would make it really easy to write entire "books" using TracNav, then export them as a single document or PDF.

Example syntax:


Would go through the TOC, and pull out all of the pages, rendering it as one big non-editable page.

Good idea? Bad idea?

Comment by anonymous on Wed Oct 4 22:49:46 2006

Great Macro. A minor documentation error, however, persists in, concerning the 'Installation' section: Contrary to what is mentioned, the file tracnav.css must not be copied in the templates subdirectory of your Trac project, but in the htdocs subdirectory.

Bodo Schulze

Fixed in r3076, thanks!

Comment by anonymous on Mon Oct 9 11:21:22 2006

Hi. I have installed the egg, setup a TOC page (TracNav/TOC) but when I use [[TracNav(TracNav/TOC)]] I get the following:

Error: Failed to load processor TracNav

No macro named [[TracNav]] found

I am using trac 0.9.6 and have setuptools 06c3 installed. What am I going wrong?

Comment by aldrinleal at gmail dot com on Fri Nov 3 18:31:56 2006

Just an idea: any way to make TracNavToc indempotent? I'd like to have a brief overview page pointing to each topics, but having a general "Full Page" listing.

There's a sample here. Any ideas?

Comment by Lars Persson Fink on Mon Nov 13 15:06:18 2006

I'd like to use TracNav to display a call tree, with links to files in the subversion repository (for example [source:filename.c@#L123]). I would like to have the TracNav and the source display side-by-side. Is that possible somehow?

See #264 for a possible solution. With this enhancement, usage of the toc is not restricted to wiki pages anymore.

Comment by Gunnar Johansson on Thu Jan 4 14:35:22 2007

I've installed TracNav on the latest trunk 0.11dev (rev 4507) and get the following error:

Error: Macro TracNav(Menu) failed 'Formatter' object has no attribute 'args'

Browsing through the source it seems like in trac/wiki has changed functionality, is there some easy fix to this?

Any hints appreciated.

See #267.

Comment by ilias@… on Fri Jan 5 00:04:20 2007

works fine for me with 0.11dev.r4353.

You may want to file an ticket.

Comment by NiNiX on Mon Jan 8 16:23:26 2007

inline display support, like TocMacro ?


Comment by Michael on Wed Apr 4 13:19:09 2007

Sorry. My TracNav shows me every time:

TracNav menu edit TOC "TOC" is empty!

I followed all instructions on the TracNav Page, check the Sandbox,... please help me.

Comment by Dennis on Fri Sep 7 10:25:38 2007

Same problem as for Michael Trac TracNav 3.92

Comment by Andi on Thu Nov 22 01:20:48 2007

Not working for 0.10.4 either...

Comment by Andi on Thu Nov 22 01:34:15 2007

Well, actually it does - the docs are not very clear about this. Just create a page called TOC that contains the menu...

Comment by korey on Tue Nov 27 15:33:39 2007

I am having the same problem as Micheal & Dennis, Trac TracNav 3.92 do i need to upgrade to 0.10.4?????? and i tried andi's comments

In order for the macro to display something, there must exist a wiki page containing the table of contents. Default is "TOC", but you can use any other page and supply its name as an argument to the macro. Note though, that there must be a valid toc structure on that page ;)
If it still doesn't work, submit a ticket, giving more details (configuration, log files, contents of your toc page, etc.)

Comment by David on Tue Dec 4 02:37:16 2007

TracNav always responds with Error: 'module' object has no attribute 'execute' what's wrong with it

Comment by David on Tue Dec 4 02:38:29 2007

I am using trac0.10.4

TracNav was converted from a macro to a plugin for Trac 0.10 and later. Have a look at our installation instructions and also at the official TracPlugins docs.

Comment by dukat on Sun Jan 20 03:34:22 2008

I tried the easy_install install method as described on the Trac Module installation page, and this was a big mistake, as it wouldn't run (Failed to load processor TracNav). Took me quite some time to figure this out, after undoing this and just placing the .egg in the plugin folder everything worked as it should!

See TracPlugins.

Comment by marikk on Thu Mar 6 11:04:57 2008

I need TracNav in combination with the CombineWiki-Plugin. Using the CombineWiki-Plugin, when moving an index(TOC)-page from left to right it needs automatically be recognized by CombineWiki or maybe the methods of TracNav that the links of the TOC will be added on the right side ("Exported Pages") as pages instead of the index(TOC)-page. Unfortunately I don't have much experience neither with javascript nor with python to implement it by myself. Maybe some methods of TracNav could be used to realize it. Thank you for efforts!

Comment by Jorrit on Sun Mar 9 14:13:59 2008

Cool plugin, one problem however. On Trac 0.11b1 with TracNav 4.0pre6 and 3.92 all menus get a header saying "TracNav menu". Am I missing something here, can I remove that or have it replaced with my own header?

This is normally a sign of a missing tracnav.css. Did you set-up the plugin cache properly?

Comment by Jorrit on Sun Mar 16 15:18:52 2008

That helps! Thanks!

Comment by TomB on Wed Apr 2 15:57:29 2008

Hi together :)

My installation doesn't work as it should ;( I'm using version 0.8.1. I've downloaded the right package imho and followed the instructions on this site (

But it always says: Error: Macro TracNav(None) failed invalid syntax (, line 1)

Any suggestions? Many Thx!

Comment by moschny on Sun Jun 1 01:57:40 2008

Comments are temporarily disabled, until we've put something in place to prevent spam on this page.

Last modified 14 years ago Last modified on Jun 1, 2008 1:58:25 AM