SmartRelink PL

for use with Adobe® InDesign®.

Fix broken image links. SmartRelink PL hunts down the missing files, shows you what it found in a simple text report, and relinks only what you approve. One Undo takes it all back.

SmartRelink PL is free and fully functional. Donations are welcomed: to donate, click the Donate button in PluginInstaller after installing SmartRelink PL

What It Does

A job folder gets moved, a server gets renamed, a colleague sends you a document and a zip of images, and InDesign’s Links panel turns into a column of red question marks. InDesign’s own relinking tools need you to point them at the right folder, and they do not show you which other files with the same name are lying around.

SmartRelink splits the job in two:

LinkReport searches the folders around your document and around where the images used to be, and writes a plain-text link report next to the document. For every image it lists where the document links to now, the best replacement it found, and any other files with the same name. It changes nothing in the document.
You read the report in your text editor and change whatever you like: pick another candidate, type in a path, use search-and-replace on the paths.
ApplyReport relinks the document exactly as the report says, as a single undoable step.

Because the report is just text, you see every decision before it is made, you can keep it as a record of what was relinked, and you can fix a hundred paths with one search-and-replace.

SmartRelink is also useful when nothing is broken: the report lists other copies of your linked images that it found nearby, so you can switch a link from, say, a low-resolution placeholder to the final high-resolution file.

Requirements

Adobe InDesign 2024 or newer, on macOS or Windows.
The document must have been saved at least once: the report is stored next to it, and the paths in the report are relative to the document’s folder.
A plain-text editor to review the report (TextEdit, Notepad, BBEdit, Visual Studio Code, …).

Installing

SmartRelink is installed with PluginInstaller, Rorohiko’s free installer and license manager.

Download and install PluginInstaller from https://plugininstaller.com
Launch PluginInstaller and find SmartRelink PL in the list of available software (type Smart in the search field to search and find the script).
Click to download and install it. You do not need to register an account for SmartRelink PL.
If InDesign was already running, restart it.

SmartRelink then appears in InDesign’s Scripts panel (Window > Utilities > Scripts), in a SmartRelink.<version> folder under User, with three entries:

LinkReport — searches for the images and writes the link report. Relinks nothing.
ApplyReport — relinks the document according to the report.
Copy Sample Files to Desktop — copies a demo document with deliberately broken links to your desktop and opens it, so you can try SmartRelink without risking a real job.

To check for updates to SmartRelink PL later, run PluginInstaller: it will show a red dot when updates for any installed additions are available. To remove SmartLink PL, uninstall it from PluginInstaller.

Quick Start: the Demo

The quickest way to learn SmartRelink PL is the demo.

Double-click Copy Sample Files to Desktop in the Scripts panel. It creates a SmartRelinkDemo folder on your desktop and opens SmartRelinkDemo.indd.

The five images in this document were linked from /Volumes/OldServer/Jobs/SmartRelinkDemo/Links, a server that no longer exists. The images themselves now live in subfolders of the Photos folder next to the document:
```
SmartRelinkDemo/
    SmartRelinkDemo.indd
    Photos/
        Coast/coast.jpg
        Coast/harbour.png
        Forest/forest.jpg
        Teaser/HighRes/teaser.jpg
        Teaser/LowRes/teaser.jpg
```
gone.jpg is not there at all.
Double-click LinkReport. It tells you that 5 images are missing and asks whether to search. Click Yes. When it is done, it writes SmartRelinkDemo_LinkReport.txt next to the document and opens it in your text editor.
Read the report. You will find:
- coast.jpg, harbour.png and forest.jpg: found, with the replacement already filled in.
- teaser.jpg: two candidates at the same distance, HighRes and LowRes. SmartRelink will not guess, so both are commented out. Remove the # in front of the one you want.
- gone.jpg: not found anywhere. Leave it, or type a replacement line yourself.
Save the report.
Double-click ApplyReport. It shows how many links it will relink and asks for confirmation. Click Yes. The images appear.
Choose Edit > Undo once: every relink is reverted in one step. Redo, or run ApplyReport again.
Run LinkReport again. The links that are now fine are still listed, together with the other copies of each image that SmartRelink found nearby. Remove the # in front of one of those, run ApplyReport, and that link now points to the other file. This is how you swap teaser.jpg between the low- and high-resolution versions.

To start the demo over, close the document, delete the SmartRelinkDemo folder from the desktop, and run Copy Sample Files to Desktop again. If the folder is already there, the script leaves it alone and just opens the document.

Everyday Use

Open and save your document.
Run LinkReport. If any images are missing, confirm the search.
Review and edit <Document>_LinkReport.txt, which opens automatically.
Run ApplyReport and confirm.
Check the result. Edit > Undo reverts the whole relink if needed.
Optionally run LinkReport again to get a fresh report of the relinked document.

You can run LinkReport as often as you like. It never relinks anything, and it keeps your own edits to the report (see Running LinkReport Again).

The Link Report

For a document Job.indd, the report is Job_LinkReport.txt in the same folder. It is a plain text file in INI format: [Section] headers, key = value lines, and comment lines starting with #. It is both the report on the links and the settings file for SmartRelink PL.

The report starts with the [Link] sections, so the part you need is at the top. The full explanation follows under [Documentation], then the search settings under [Preferences], and at the end [LinkReport] records which document and when.

A typical report looks like this:

# SmartRelink link report for Job.indd: review and edit the [Link] sections below, 
# then run ApplyReport. ...

# photo.jpg: missing. Suggested replacement: name match at distance 2.
[Link]
original = /Volumes/Old/Job/Links/photo.jpg
suggested = Links/photo.jpg
replacement = Links/photo.jpg
# replacement = ../Archive/photo.jpg

# logo.eps: missing, 2 candidates. Uncomment one replacement to use it.
[Link]
original = /Volumes/Old/Job/Links/logo.eps
# replacement = A/logo.eps
# replacement = /Volumes/Other/logo.eps

# gone.tif: missing, no candidate found. Add a replacement line to relink it.
[Link]
original = /Volumes/Old/Job/Links/gone.tif

# banner.psd: ok. Uncomment a replacement to relink to another file.
[Link]
original = /Users/me/Job/Links/banner.psd
# replacement = ../Other/banner.psd

[Documentation]
# ...

[Preferences]
maxSearchDistance = 6
maxAlternateDistance = 3
maxFoldersScanned = 5000
maxSearchSeconds = 30
maxClimbLevels = 3
# resolutionPreference = high
# searchRoot = /Volumes/Server/Images
# excludeFolder = Archive

[LinkReport]
document = Job.indd
timestamp = 2026-10-16T10:15:00Z

The [Link] Sections

Each [Link] section is one linked file. If the same image is placed several times in the document, it is one section, and relinking it relinks every placement.

original — where the document links to now, exactly as InDesign reports it. This is how SmartRelink finds the link again; do not edit it.
replacement — the file to relink to. A line with no # in front of it is active. ApplyReport relinks a section only when it has exactly one active replacement.
suggested — for a missing image, the best candidate SmartRelink found. It is informational only: the active replacement line is what counts.

What you will see, per kind of link:

Situation	What the report contains
Missing, one best candidate	`suggested` and an active `replacement` with that candidate; other candidates commented out.
Missing, several equally good candidates	All candidates as commented-out `replacement` lines. You choose.
Missing, nothing found	Only `original`. Add a `replacement` line if you know where the file is.
Not missing	Only commented-out `replacement` lines for other copies found nearby. Uncomment one to switch to it.

Paths in replacement lines are relative to the document’s folder and use / on both Mac and Windows, e.g. Links/photo.jpg or ../Archive/photo.jpg. A file on another disk or volume is written as an absolute path. You can type either kind yourself.

Editing the Report

Accept a suggestion: do nothing.
Reject a suggestion: put a # in front of the active replacement line. That link is then left alone.
Choose another candidate: remove the # in front of the one you want, and put a # in front of the line that was active.
Type your own: add a line replacement = path/to/file.jpg.
Move a whole batch: search-and-replace on the paths in your text editor, e.g. replace Links/ by Links_Final/.

Save the file before running ApplyReport.

How Candidates Are Found and Ranked

SmartRelink searches outward, folder by folder, starting from:

the folder each image used to be in (or, when that folder no longer exists, the nearest folder above it that does),
the document’s own folder,
any extra folders you list as searchRoot in [Preferences].

From each of these it looks into subfolders and climbs up into parent folders, one step at a time. The number of steps from a starting folder to where a file was found is its distance: lower is better. Files are matched by name; upper/lower case and differently encoded accented characters (common on macOS) do not prevent a match.

When several files with the right name are at the same, lowest distance, SmartRelink tries, in this order, to pick one:

Folder moves. Images that lived in the same folder usually moved together. If the other images from that old folder were all found in one new folder, the candidate in that folder wins. This also finds images that are further away than the search would otherwise reach.
File size. InDesign remembers the size of each linked file. If exactly one candidate has that size, it wins.
Resolution preference. If resolutionPreference is set to high or low in [Preferences], the candidate with the most or fewest pixels wins. This works for PNG, JPEG, TIFF, PSD/PSB and GIF; with vector files (PDF, AI, EPS) or a tie, it does not decide.
Otherwise, you decide: all candidates are listed, commented out.

To keep the search quick and safe, SmartRelink PL:

does not climb more than maxClimbLevels folders above an image or document folder, and never into the top of a disk, /Volumes, /Users, or your home folder itself (too large to search). For a document on the desktop, it searches the desktop folder; add a searchRoot for anything else.
skips hidden folders, application and package bundles, and folders named node_modules, __MACOSX, $RECYCLE.BIN and System Volume Information, plus any excludeFolder names you add.
stops at the first of: maxSearchDistance steps, maxFoldersScanned folders, or maxSearchSeconds seconds. The report lists whatever was found up to that point, and the result dialog says when the folder or time limit was hit.
stops early once every missing image has a candidate and it has gone past maxAlternateDistance (it is then only looking for other copies of images that are fine, which is not worth a long search).

Placed text files and embedded images are not included.

Preferences

All settings live in the [Preferences] section of the report. Change them, save, and run LinkReport again. They are kept from one run to the next. The first time you run LinkReport on a document, the defaults are used.

Setting	Default	Meaning
`maxSearchDistance`	`6`	How many folder steps to search outward from where the images used to be and from the document’s folder.
`maxAlternateDistance`	`3`	How far to look for other copies of images that are not missing. Missing images are searched for further out, up to `maxSearchDistance`.
`maxFoldersScanned`	`5000`	Stop after this many folders.
`maxSearchSeconds`	`30`	Stop after this many seconds, however many folders are left. Network and cloud folders can be slow.
`maxClimbLevels`	`3`	How many folder levels the search may climb above the image folders and the document folder.
`resolutionPreference`	not set	`high` or `low`: when equally good candidates remain, prefer the one with the most or fewest pixels. Without it, you choose.
`searchRoot`	none	An extra folder to search, e.g. an image archive on a server. Relative paths start from the document’s folder. Repeat the line for more folders.
`excludeFolder`	none	A folder name to skip, e.g. `Archive` or `Old`. Repeat the line for more names.

Example: search an archive server too, skip Rejects folders, prefer high-resolution images, and allow a minute for the search:

[Preferences]
maxSearchSeconds = 60
resolutionPreference = high
searchRoot = /Volumes/Server/Images
excludeFolder = Rejects

Running LinkReport Again

LinkReport rebuilds the report from the document every time, but keeps your work:

Your [Preferences] are kept.
A replacement you typed, edited, or uncommented is kept as it is.
A suggestion you commented out stays off, unless the search now comes up with a different best candidate.
Suggestions you did not touch are recomputed with the current settings.
Sections for links that no longer have that original path are dropped. This is normal after ApplyReport: those links now point to their replacements.

Comments you add by hand are not kept.

ApplyReport

ApplyReport reads the report, checks every [Link] section, and then shows a summary and asks for confirmation before relinking anything.

For each section:

No active replacement: left alone.
An active replacement on a link that is not missing: relinked. An active replacement is always an instruction, so you can use it to swap a good link for another file.
The replacement is the file the link already points to: counted as already linked.
No link in the document has that original path any more (for example, a report from before an earlier ApplyReport): counted and skipped.
Problems — more than one active replacement, or a replacement file that does not exist: not applied. ApplyReport marks each problem section in the report with a # ApplyReport: ... line above its [Link] header and opens the report, so you can find and fix them. The marks disappear the next time you run LinkReport.

All relinks happen as one undo step: Edit > Undo reverts them all.

After ApplyReport, the report is out of date. Run LinkReport again to refresh it.

Which Text Editor Opens the Report

LinkReport opens the report in:

the editor set as “Editor program” in Rorohiko’s Scripts Panel OT, if you use it; otherwise
the program your computer opens .txt files with.

If the report cannot be opened automatically, the result dialog says so. You will find it next to the document.

Troubleshooting

“save the document first” — SmartRelink needs a saved document, because the report is stored next to it. Save, then run LinkReport again.
“There is no report for this document” — run LinkReport before ApplyReport. The report must be named <Document>_LinkReport.txt and be in the same folder as the document.
An image you know is there was not found. It may be beyond the search limits. Add its folder as a searchRoot, or raise maxSearchDistance, maxClimbLevels or maxSearchSeconds, and run LinkReport again. Or type the replacement line yourself.
The search takes too long. Network, cloud-synced and protected folders can be slow to list. Lower maxSearchSeconds, add excludeFolder lines for large folders that will not contain the images, or point a searchRoot straight at the right folder.
The same file is listed twice under slightly different paths. This can happen when a folder is reachable through a shortcut (alias or symbolic link) as well as directly. Either path works.
A link was not relinked. Check that its section has exactly one active replacement line, and look for an # ApplyReport: problem mark above it.
Links from a document made on the other platform (a Windows path on a Mac, or vice versa) give the search no starting folder. SmartRelink still searches around the document’s folder and any searchRoots.
“This is an unexpected internal error” — the message names a folder. Create a file prefs.json in that folder with the following contents, run the script again, and send the log file to [email protected]:
```
{ "logLevel": 4, "logEntryExit": true, "logFile": "/Users/me/Desktop/SmartRelink.log" }
```
Change the logFile path to a location on your own computer (on Windows, e.g. C:/Users/me/Desktop/SmartRelink.log). Delete prefs.json afterwards to turn logging off again.

Known Limitations

Files are matched by name only. A renamed image is not found; type its replacement line yourself.
Placed text files and embedded images are ignored.
A single very slow folder (for example on a disconnected network share) cannot be interrupted; the time limit is checked between folders.
Comments you add to the report are not kept when LinkReport rebuilds it.

Contact

SmartRelink PL is made by Rorohiko. Questions, bug reports and suggestions: [email protected]

Silicon Publishing automates content at scale, with over two decades of experience building the largest InDesign Server solutions on the planet.	Catalog Automation builds and automates catalogs, directories, and data-driven publishing for businesses large and small, turning catalog nightmares into push-button production.


The Creative Coding Collective is a worldwide community of creative-software developers: Slack channel, LinkedIn group, meetups, an annual summit... Shared knowledge, on the principle that a rising tide lifts all boats.	CreativePro is the world’s most trusted resource for design professionals — expert tutorials, tips, and training in InDesign, Illustrator, Photoshop, and more.