RSS

Confluence Link Types Explained

This post shows the different link types in Confluence and highlights the difference between soft links and hard links. It covers the relevance of knowing link types and variations for migration tools.

Migration tools like WikiTraccs needs to take care of Confluence links, because otherwise those are broken after a migration.

WikiTraccs will translate links within Confluence to proper SharePoint links. This includes page links, space links, and attachment links.

There is one challenge for migration tools when analyzing Confluence links and that is properly detecting both the two link types (soft links and hard links), and the different hard link variations.

I get that asked quite a lot. From an end user perspective the difference normally is not visible.

Here is an example of one soft link and one hard link, both linking to another Confluence page, as seen by an end user:

Can you spot the difference?

The difference can only be seen when looking at the page’s storage format, which looks like this:

<ac:link>
   <ri:page ri:space-key="linktarget" ri:content-title="Get the most out of your team space"
      ri:version-at-save="1" />
   <ac:link-body>Get the most out of your team space</ac:link-body>
</ac:link>
<a
   href="//wikitransformationproject.atlassian.net/wiki/spaces/linktarget/pages/60162329/Get+the+most+out+of+your+team+space">Get
   the most out of your team space
</a>

This is how tools like WikiTraccs “see” the page when migrating it to SharePoint Online, or processing it in any other way.

The first link - a soft link - is represented as ac:link element that has metadata attached that allows WikiTraccs to look up information about this page.

The soft link contains readily available metadata, like the target space key (linktarget) and the title of the page (Get the most out of your team space). This is easy to handle for a tool like WikiTraccs. And most importantly, Confluence is able to keep this link up-to-date even if the target page changes.

The second link - a hard link - is a plain HTML link. It also points to the target page, but uses the absolute page address to do so.

The hard link doesn’t contain easily accessible page metadata. If you look closely you’ll see information like the space key, page ID, and so on; those certainly help, but there are many variations of those links, and we look at those further down. Confluence will not keep hard links up-to-date, so, if the target page changes, the link might be broken.

Let’s create one.

Ideally, there shouldn’t be hard links at all. When pasting a link onto a Confluence page, Confluence analyzes the link, detects the content it links to, and creates a proper soft link.

Nevertheless, hard links are often present in more complex content that has been copy and pasted into pages. Confluence’s hard link conversion does not always kick in.

Here’s a sample of how to fool the hard link detection and create a soft link and a hard link:

Above animation shows the following:

  1. we copy a link to a Confluence Cloud page to the clipboard
  2. we paste the link as plain text
  3. Confluence recognizes that this is a hard link and converts it to a soft link
  4. we change the settings of that soft link to look like a regular link
  5. we paste the link a second time
  6. we edit the second link to remove the https: part; the result is still a proper and valid hard link, but it fools Confluence’s logic and it leaves the hard link in place
  7. we save the page

The result is a page containing one soft link and one hard link.

It is relevant if you migrate content from one Confluence environment into another environment.

So, it is relevant for those use cases:

  • Confluence Cloud site to site migrations
  • Confluence Data Center to Confluence Cloud migrations
  • Confluence to SharePoint Online migrations

In all those cases, links between migrated pages will be broken, as well as links from external systems, like Jira descriptions and comments.

To fix those broken links, you need to:

  1. identify the links
  2. modify the links to point to the new location (or redirect)

Knowing that hard links and soft links exist is crucial for identifying the links in the first place.

Ideally, migration tools cover that, so you don’t have to care. WikiTraccs covers this.

We used a very simple hard link example so far (from Confluence Cloud):

wiki/spaces/linktarget/pages/60162329/Get+the+most+out+of+your+team+space

This link contains lots of metadata to look up the target content:

  • content type (page)
  • content ID (60162329)
  • space key or alias (linktarget)

Here’s a list of other hard link variations:

  • wiki/display/Test (space link)
  • wiki/spaces/Test (space link, cloud)
  • wiki/pages/viewpage.action?pageId=10162329 (page link)
  • wiki/pages/viewpage.action?pageId=10162329&pageVersion=1 (link to page version)
  • wiki/x/xYBtAQ (tiny page link)
  • wiki/display/Test/news (page link)
  • wiki/spaces/Test/blog/2024/10/24/181542831/news (blog post link, cloud)
  • wiki/spaces/Test/blog/181542831 (blog post link, cloud)
  • wiki/spaces/Test/pages/edit-v2/2123259301 (page edit link, cloud)
  • wiki/pages/viewpageattachments.action?pageId=60162247&preview=/60162247/174891441/image.png (attachment view link)
  • wiki/download/attachments/10162247/image.png (attachment download link)

Wrap

In this post we learned about soft link and hard links, and looked at different hard link variations.

When moving content from one Confluence environment to another environment (Confluence, SharePoint Online, …) links to pages, attachments, and spaces will break. Those links need to be taken care of, either by tools like WikiTraccs, or proxy solutions that recognize those links and redirect to the new location.