Link Steward for Confluence / Release 1.0
Check and replace links in Confluence Cloud
Use Link Steward to find broken links in a Confluence page or space, review issues with page owners, and replace URLs after checking a preview. This guide covers setup, scheduled scans, and the limits of each check.
Set up a space and run a link scan
Marketplace review is in progress, so public installation is not yet available. Once the app is available and installed, open Apps → Link Steward for Confluence. Choose a space. A Confluence space administrator can configure and scan it.
In Settings, enter exact external hostnames, one per line, such as docs.example.com. Include redirect destinations if those are also trusted. Internal Confluence page links are checked without an external-domain rule. External checking is disabled until a domain is enabled.
Choose Off, Daily or Weekly automatic checks, then save. Scheduled checks start within approximately an hour after becoming due, subject to Forge availability and quotas. A manual scan can be started immediately. Only one space scan runs at a time. Use Stop scan to stop a stalled or unwanted run and start a fresh one.
Find broken links in a space or page
- Choose the space you want to check and enable the external hostnames in Settings.
- Select Scan space and wait for results. For a single page, open More actions → Apps → Link Steward for Confluence and select Check this page.
- Filter by Broken to review confirmed external 404 or 410 responses. Review Needs review separately for access restrictions or inconclusive checks.
- Use the current page owner's queue to track the issue, then recheck the page after a fix.
Review link results and owner queues
My queue follows the current Confluence page owner. All links includes only pages you can currently read. Use search, owner, work-state and link-result filters. When page ownership changes, the link issues move to the new owner's queue after refresh. If an owner profile is unavailable, an administrator can still manage accessible issues and transfer ownership in Confluence.
| Link result | Meaning |
|---|---|
| Available | An enabled external destination returned a successful response, or the Confluence target is accessible. |
| Broken | The public external destination returned HTTP 404 or 410. |
| Needs review | Permissions, authentication, throttling, network trouble, configuration or unsupported content prevent a conclusion. |
| Excluded | A space rule prevents this destination from being checked. |
| Link removed | A later check confirmed that the URL no longer appears on the source page. |
Mark in progress records work. Ignore leaves an exception outside the default queue. Reopen restores it. Recheck queues the page for another check. Success or confirmed removal resolves an earlier issue; a later failure opens it again. A link that has always been available has No issue and does not inflate the count of fixes.
Select up to 50 rows for work-state changes or page rechecks. Use Owners to review progress and recent scans. Export CSV downloads the currently filtered, loaded results. Share exports only with people entitled to the page titles, URLs and owner names they contain.
From a page, open More actions → Apps → Link Steward for Confluence to review only that page and use Check this page. Show whole space returns to the space report.
Find and replace URLs across Confluence pages
Select results on the pages to edit, choose Replace links, and enter the old and new destinations. An exact replacement matches the complete URL. A base replacement matches the origin and path boundary and preserves the remaining path, query, and fragment of each matching link. It does not rewrite visible link labels.
Choose Preview changes. Review the old/new destinations and selected pages, then save. Up to 20 pages can be included. Keep the view open until every page has a result; each successful save creates a Confluence version. A failed page does not undo already saved pages. If the page or its unpublished draft changes, create a new preview. Use Confluence version history to restore a previous page version when necessary.
Exact and base URL replacement examples
Use exact mode when one destination has changed. Use base mode when a documentation site moves to a new domain or path and the remaining URL structure stays the same.
| Mode | Replacement rule | Result |
|---|---|---|
| Exact URL | Replace https://docs.example.com/old-guide with https://docs.example.com/new-guide. | Only links matching the complete old URL are replaced. |
| Base URL | Replace https://old.example.com/docs with https://new.example.com/help. | https://old.example.com/docs/setup?lang=en#install becomes https://new.example.com/help/setup?lang=en#install. |
Base mode matches a path boundary: /docs matches /docs/setup, but not /docs-old. Enter base URLs without a query or fragment and use an HTTPS destination. Link Steward replaces link destinations, including supported Smart Links; it does not find and replace ordinary page text or visible link labels.
A domain change does not guarantee that every old path exists on the new site. Review each preview and recheck the pages after saving. If a replacement fails, see replacement troubleshooting.
Exceptions and reminders
Domain exclusions skip all matching destinations. Select rows and choose Exclude URLs for exact URL exclusions across a space. Remove a rule in Settings and recheck the affected pages to update results.
Owner reminders are off by default. Enabling them lets Link Steward add a native page comment mentioning the current owner when that page has open, confirmed broken links. Ignored, in-progress and uncertain results do not trigger reminders. Repeated checks do not repeat the comment within seven days. Confluence may notify watchers according to their preferences; email delivery is not guaranteed.
Supported links, scan limits, and recovery
Link Steward reads standard hyperlinks and inline, card, and embed Smart Link destinations in published Confluence pages. It checks supported internal page targets without an external-domain rule. External destinations must use public HTTPS hostnames enabled by a space administrator.
A space scan checks at most 1,000 published pages and 10,000 links, with at most 100 unique links per page. If a scan reaches a limit or cannot read a page’s content, the result is incomplete. Archived, deleted and inaccessible source pages are not exposed in your report. Plain text URLs and third-party macro internals are not scanned. URL fragments and content meaning require manual review.
Results and work states expire after 30 days. Removed-link results are retained for up to 30 days. Each page can have up to 200 stored results, including current and removed links. Refresh after an action to see asynchronous results. Retry a failed scan when the service is available again.
Delete data and uninstall
Turn off schedules and reminders in Settings. A space administrator can choose Delete app data for this space and confirm. This clears configuration, results and work states for that space. Existing Confluence page versions and reminder comments remain Confluence content; app data deletion does not erase them. Site administrators can uninstall Link Steward in Connected apps. Atlassian's platform retention policies apply after uninstallation.