It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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

Jon Prapuolenis Oct 03, 2017

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
This widget could not be displayed.
This widget could not be displayed.
Community showcase
Published in Confluence

6 Awesome Ways to Apply Trello, JIRA and Confluence to your Project

I attended  Atlassian Summit 2019  and learned a lot from the presenters, attendees and knowledgeable Atlassian product managers. The presentations I attended focused on applying Agile, pla...

937 views 7 17
Read article

Community Events

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

Find an event

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

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you