Table of Contents (ToC) macro and headings as anchors possible at the same time?

Currently I've been trying to figure out a way to generate anchor links for headings on a confluence page similar to what the table of contents macro is able to do. More specifically, exactly like the table contents macro, but where the headings that the macro links down to can be clicked on for the same effect. 

How we use Confluence primarily is to create massive pages of documentation on a variety of specific topics, all organized by headers. In the course of making and reviewing decisions we find it useful to link to the documentation specific to those topics so everyone involved in the process can be on the same page or be aware what documentation needs to be updated. The table of contents is a very useful way to provide that link to specific parts of our long documentation pages (scroll bars for days) but as the pages get longer and longer it can be inconvenient to scroll up to the top while remembering which of several similar heading titles was related to the documentation you were trying to link to. Added to this, we often quickly search through our documentation with a control-f keyword search instead of scrolling through the table of contents in the first place, making the whole thing an out of the way link repository in those instances. 

In looking for solution to this problem it is important to find a solution that is automated. I was unable to find a prebaked solution in Confluence, though as we are on a sever version of confluence custom JavaScript solutions are an option. The closest related guidance I've found on how that might look is:

which importantly DOESN'T involve working around the Table of Contents macro. 

While utilizing the wiki markup of Confluence to specify the headers as anchor links seems to be a more straight forward way of adding the desired functionality, the shear amount of headers that would need to be linked by hand and the potential for inconsistency going forward when new sections are added make this option less than attractive. Even if there were far fewer headings to work with, and no issues with making sure every new heading added had the wiki markup linking, there seems to be some very strange interactions with linking to headings when the ToC macro is in play. For instance, sometimes when going to a url generated by an anchor link on a page, you will be sent to the correct part of the page initially, but as soon as the table of contents loads in you are shot back to the top of the page, defeating the point of linking to specific point on a page. 

For both a manual and programmatic method of creating these links the consistent sticking point seems to be working around the Table of Contents macro, which we are not interested in removing from our pages. Frustratingly, the ToC macro seems to be doing 90% of the internal work to gather the specified headings and assign them links in the ToC, but providing no apparent way to get that final 10% and have the headings function as links themselves or do something akin to the headings on this Python documentation site:


Is there some way to get this functionality out of the ToC macro that I'm missing, or has anyone figured out a solution that works in tandem with the ToC macro? 

1 answer

1 vote
Ann Worley Atlassian Team Oct 09, 2017

Thanks for the detailed description of your use case. I understand you like the way the TOC macro works at the top of the page but when you get further down on the document it is less useful.

It is possible to put the TOC macro in the sidebar as in the Python documentation you linked, but the functionality is not working fully as expected at the moment due to TOC macro in sidebar creates invalid URL. Please do comment and/or vote on it to influence the development team.

In the meantime, the workaround is to add "absoluteUrl=true" to the wiki markup for the sidebar, for example:


Suggest an answer

Log in or Sign up to answer
Community showcase
Published yesterday in Confluence Cloud

Happy holidays from our team to yours!

Hi Community!  2018 was filled with changes for our team, both big and small, and we've taken a lot of time to both celebrate our wins and recognize areas of improvement. One thing that we're a...

102 views 1 14
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you