How to Find and Replace Links in Confluence Cloud After a URL Change

The example: the VPN page moved

In the Support Handbook space, the IT support runbook has a link VPN setup that points to https://example.com/old-vpn-setup. The VPN instructions now live somewhere else, and every page that links to the old address has to follow.

Before you touch any page, open the new VPN page yourself and confirm it answers the same question. A move is rarely “replace one string everywhere”: one old page may have a direct successor, another may have been split or retired.

Check: the new address opens the instructions that should replace the old ones.

1. Find pages that use the old address

You do not need to know the page names. On the test site, Confluence search matched text inside link addresses: a fragment that existed only in a link URL found the page and showed the full address in the excerpt. Search for a distinctive part of the old URL, such as its last path segment, then check each result.

1 2 Enlarge Enlarge screenshot

Pick a fragment that ordinary text is unlikely to contain: old-vpn-setup is better than vpn, a full path is better than a domain. For a confluence cleanup after a domain move, repeat the search for every old address in your mapping.

Check: every page that really contains the old address has a row in your worksheet.

2. Map old and new addresses

Use one row per source page and old URL. If one address appears on five pages, that is five rows: one page may have different link text, a different owner or need a different replacement.

The worksheet also has columns for the match mode, reviewer, published version, recheck result and notes. When you track broken links after migration this way, the old destination fails everywhere at once, but each repair is still closed page by page.

Check: every row has one intended new address, or is marked as an exception.

3. Why Find and replace is not enough

The editor has its own Find and replace (⌘+F or Ctrl+F inside the page). Atlassian describes it as a way to find and replace page text. On the tested page, Find returned “No results” for old-vpn-setup, although the VPN setup link points to that address.

1 2 Enlarge Enlarge screenshot

This is the main trap behind searches for confluence find and replace and confluence search and replace: on the tested page, Find and replace did not search the address behind the link text. Replacing the words “VPN setup” leaves the old URL in place. Use Find and replace for text; use Edit link when the destination moved.

Check: you are about to edit the link destination, not only the words readers see.

4. Change the link destination

1. 1

   Step 1: Open the link dialog

   Open the IT support runbook and select Edit. Click VPN setup and choose Edit link in the small toolbar.

2. 2

   Step 2: Paste the new address, save, update

   1 2 3 4 Enlarge Enlarge screenshot

   A domain move usually needs a new URL while “VPN setup” stays perfectly good link text. Until you select Update, readers still get the old address.

Check: the published page shows the new address behind the link.

5. Recheck and repeat

Leave the editor and follow the link from the published page. Confirm that it opens, that it reaches the intended VPN instructions, and that the link text still describes them. Mark the row done only after this check.

Then repeat for the next page. With the editor, the work is page by page: search → open page → Edit link → Save → Update → recheck. Eight pages mean eight edits, eight updates and eight rechecks, plus time for exceptions. Keep the worksheet as your work list for confluence links, not browser tabs and memory.

When you finish, search for the old fragment once more. Any result whose excerpt still shows the old URL needs another look. This is a final check for leftovers, not proof that search found every page.

Patterns and exceptions

A confluence change url task is not always one old URL → one new URL.

For a whole area, such as https://old.example.com/docs/… moving to https://new.example.com/help/…, do not assume every path survived. Open a few real destinations and put the exceptions in the worksheet. For links to a section, copy the heading link from the new page: hover to the right of the heading and select the link icon. Atlassian: Insert links and anchors

Confluence page links

For confluence page links to other Confluence pages the rule is the same: open the current page or heading, copy its link and edit the source link. Do not rely on Space settings→Content→Undefined for this: it lists links to pages that do not exist yet, not external addresses. In the test space it was empty although two links returned 404. To find those, see How to Find Broken Links in Confluence Cloud.

After moving the Confluence site itself

If the old address is your own Atlassian site — after a Data Center to Cloud or a Cloud to Cloud migration — there is a separate admin tool. In Atlassian Administration, Data management→Link fixing updates links that still point to the old site address in bulk. It needs an organization admin who is also an admin of the app, and Atlassian recommends spot-checking links afterwards. It does not cover other addresses, such as a documentation site that moved. Atlassian: Update links after migration

A link checker can find failing links and recheck them, but it cannot decide that one new document is the right successor for an old one.

Before you close the move

• Every old URL has a mapping or a written exception.
• Every search result that contains the address is in the worksheet.
• The destination was changed, not only the link text.
• Every changed page was updated and opened again from the published view.
• Section links land on the right heading.
• Pages you could not edit have an owner and a next step.
• A final search for the old fragment finds nothing you meant to change.

Common questions

If the same address sits on many pages, Broken Link Checker for Confluence previews exact or base URL replacements across selected pages before anything is published. It is free for up to 10 Confluence users.