Skip to end of metadata
Go to start of metadata

This tutorial describes how to add a table of contents to the menu bar...

  • The toc macro must be installed
  • If adding the menu at theme level (i.e. in to a theme panel), you must have sufficient privileges to edit the theme configuration (e.g. be a Space Administrator)

We will initially assume that you want to add the Table of Contents at theme level in order to show the contents throughout the Space...

To do this, open the Edit menu and choose "Administration" then "Configure Theme":

The menu is usually located in the Menu Bar so from the Edit menu, choose Menu Bar and then scroll down to view the wiki notation used for the menu.

The toc macro generates a table of contents based on the headings in a wiki page (or blog post):

{toc}

For this page, that results in:

To add the table of contents to the menu bar, you need to wrap the {toc} macro in the wikimenu macro like this:

{menubar}
  {wikimenu}{toc}{wikimenu}
{menubar}

This embeds the table of contents inside your menu bar.

Obviously, if you have loads of headings on your page the menu bar will become very cluttered so it's advisible to put the contents in to their own pop-up menu:

{menubar}
  {menu}Contents
    {wikimenu}{toc}{wikimenu}
  {menu}
{menubar}

That's it - simple, eh? Now save the theme configuration.

Go to a normal page that has headings in and open the "Contents" menu:

As you can see, the menu is automatically generated from the text Headings on the page.

Now that we've added a basic table of contents to a menu, let's take a look at some alternatives...

While having the table of contents shown as hierarchical menu items is pretty neat, there are times when you want to see the full table of contents and this can be achieved as follows:

{menubar}
  {menu}Contents
    {menuitem}{toc}{menuitem}
  {menu}
{menubar}

Cool, eh?

If you're adding the table of contents to a sidebar, you should use vertical menus like this:

{menubar:vertical=true}
  {wikimenu}{toc}{wikimenu}
{menubar}

The addition of "vertical=true" makes the top-level menu appear vertically rather than horizontally.

If your pages are quite long and require scrolling, the menu will often not appear on the screen making access to the table of contents somewhat difficult. So, to provide instant access, you can create a context menu:

{menubar:context=true}
  {menu:class=context-for-document}
    {wikimenu}{toc}{wikimenu}
  {menu}
{menubar}

And the result? Well, try right-clicking this page! (big grin)

Because the table of contents is only shown on pages or blogposts, you can use the builder-show macro to prevent it appearing in other locations (such as search results or dashboard):

{menubar}
  {builder-show:context=page,blogpost|mode=view}{menu}Contents
    {wikimenu}{toc}{wikimenu}
  {menu}{builder-show}
{menubar}

If you have plenty of RAM available, you can cache the table of contents with the cache macro like this:

{menubar}
  {builder-show:context=page,blogpost|mode=view}{cache}{menu}Contents
    {wikimenu}{toc}{wikimenu}
  {menu}{cache}{builder-show}
{menubar}

The cache will automatically be cleared whenever the page or blogpost is edited so it's a really nice way to improve performance.

 Are there any other macros that create menus like this?

Yes. Any macro that outputs an un-ordered bullet list can be used. Some additional examples are given in our Automated Menu Creation tutorial.