TOC links don't work when using INCLUDE macro to display page?

We're using Confluence 3.0.1.

I want to display an entire page within another page - so I'm using the INCLUDE macro to do this.

The page that I want displayed has a TOC macro.

Problem: Even through the Table of Contents is correctly displayed on my main page, the hyperlinks don't work.

Any suggestions?

8 answers

This may not be the case in this instance - but we had troubles with this and realized the include pages had Wiki Markup inside a heading. For example:

h1.{color:#000000}{*}This is the Heading{*}{color}

We found out the mark up within the heading was disabling the table of contents and the reason our Include macros were not generating a table of contents with working hyperlinks.

This may not be the answer in your case but I thought I'd throw it out there. :)

swanj115 - thanks for the idea. Unfortunately the page doesn't have any markups similar to the ones you mentioned.

I cant explain it, but have you tried using the import macro from the adaptavist theme builder plugin ? Just be aware it might create additional sideeffects since the evaluation-context of the wikimarkup changes. (See image from : )

Differences in inclusion options

This is really a hassle. It would be nice to have a setting -- "url=local|absolute". Please.

Have you tried relocating the Toc macro to the page that uses the Include macro?

Tried that. Still no joy. :-(

Wondering if you'd found an answer to this? I've got the same problem. It looks as if the toc is displaying relative links, and of course the link doesn't exist on the current page.

Unfortunately never got an answer nor found a solution :(

Manny, I've found a workaround. It's not a very good one, but it does work.

I've been adding a manual high-level table of contents, using headings like this on the original page.

| [#First heading] | [#Second heading] |

h2. First heading

Some text

h2. Second heading 

More text

That renders like this

When you include the original page somewhere else, the manual links will work. 

What I don't understand is why that kind of relative link DOES work, but the one inside the toc macro doesn't.
Crumbs, I hate wysiwyg editors. You can't see where the code block starts and ends. This ISN'T part of the code block. Grr. And there SHOULD NOT be <br> character in the first example.

OK, I've calmed down after my wysiwyg editing experience. I also want to add some 'gotchas' you need to look out for if you create a manual toc like that. My instructions assume you're using wiki markup, not rich text.

  • Using the #Heading text local link syntax is fussy. You need to get spelling and capital letters exactly right or the link will silently fail
  • If anyone changes the words in the heading text, you also have to re-edit the link or it will break
  • It's more work, but is more reliable, to use an anchor instead of the #Heading text syntax ... so, just above the h2. (or other heading) in the text, enter {anchor:anchortext1}, then your toc link will look like this: [First heading|#anchortext1] ... by doing that, the heading text in the body of the doc can change (it won't be automatically updated) but at least your link at the top will not break.

So the code would look like this (it will still render exactly the same as the example in my first post)


| [First heading#anchortext1] | [Second heading|#anchortext2] |

h2. First heading

Some text

h2. Second heading

More text


Edit: Obviously, this is a p.i.t.a. that shouldn't be necessary if the {include} macro didn't break things. Like I said, it's not a GOOD solution, but it does work.


what the toc macro does is read the headlines from a page and create toc entries with anchor hyperlinks to these headlines.
As a result the hyperlinks of a toc entry on a PageA look like this:


=> These hyperlinks will work!

But: If PageA is included in PageB the hyperlinks of the toc entries in -now- PageB will look a little different:


=> These hyperlinks will not work!

I think there is no way to "repair" this directly.
As a workaround one could use the toc macro and adapt the hyperlinks afterwards:

  • Include the toc macro on the wiki page
  • Quit Edit mode and copy the resulting toc from the html page into the clipboard
  • Go back to Edit mode and enter the data from the clipboard into Rich Text view
  • Switch to Markup view, look for the wiki code of the toc and adapt the hyperlinks manually:
    • What you find is something like this:
      * [Anchorname|display/~Username/PageName#PageName-Anchorname]
    • Change it to this:
      * [Anchorname|#Anchorname]

I actually do this a lot ;-)

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted Feb 06, 2019 in Confluence

Try out the new editing experience

Hi team, I’m Avinoam, a product manager on Confluence Cloud, and today I’m really excited to let the Community know that all customers can now try out the new editing experience and see some of the ...

896 views 45 7
Join discussion

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