Documentation
How Linkamend works
Install
- In WordPress, go to Plugins, Add New Plugin, Upload Plugin. Choose the zip file and press Install Now, then Activate.
- Go to Tools, Linkamend. The plugin starts reading your content at once. Keep the page open to speed up the first pass, or close it and let the background schedule do the work.
- For Pro: open the Licence tab, paste your key and press Activate.
Linkamend needs WordPress 6.2 or later and PHP 7.4 or later. If you install Pro on a site that runs the free edition, the free edition is switched off and its data is kept.
The three lists
Broken
The server answered 404 or 410, the host name no longer exists, the server refuses connections, or a YouTube video has been removed or made private. A link appears here only after it failed twice, at least half an hour apart. Between the two it is counted as "failed once" above the list. If you press Check again yourself and it fails a second time, it is listed at once.
Redirected
The link reaches a working page through a permanent redirect (301 or 308). The address in your content is out of date. Linkamend tells apart three cases: the same page in a new form (https, www or a trailing slash), a page that moved, and an old page that now redirects to the front page, which usually means the page itself is gone. Temporary redirects (302, 307) are treated as working.
Could not verify
Linkamend got no usable answer: the site blocks automatic checks (403, 401, a bot wall, LinkedIn's 999), asked it to slow down (429), did not answer in time, had a server error (5xx), or has a certificate problem. Most of these links work in a browser. They are never moved to Broken, however long they stay here, and they are not in the digest mail. If you are sure a link is fine, press Ignore.
How checking is paced
- A background job runs every five minutes for at most 20 seconds at the normal pace (10 gentle, 40 fast in Pro). It never runs two at once.
- One request at a time. Between two requests to the same site it waits 2 seconds (5 gentle, 1 fast).
- Each request gives up after 10 seconds unless you change that under Settings.
- While the Linkamend page is open in your browser, it runs extra batches of up to 8 seconds, so the first pass goes faster.
- A link to your own site is settled without a request when it is your front page, a file that exists on disk, or the permalink of published content. Anything else is requested like any other link.
- Working links are checked again every 7 days (1 to 90 in Pro). A link that just broke is looked at daily for a week in case it comes back.
- If your host has switched off WP-Cron and set up no system cron job, Linkamend says so on its page and works only while that page is open.
- A batch is shortened to fit the host's limit on how long PHP may run. Where that limit is 30 seconds, a batch lasts about 7 seconds, so a large site is checked more slowly there.
- A link whose server cannot be connected to at all may be dead, or this site's own connection may be down or filtered (a firewall, a proxy, DNS). Before such a failure counts, Linkamend asks three links that worked in the last 30 days, each on a different site, chosen among those checked longest ago. The failure counts only if at least two of them answer. Otherwise nothing is counted, the screen says that the site cannot reach most sites, and checking carries on by itself. If that lasts more than three days, failures count again and the screen says why, so that a host that blocks outgoing connections for good cannot hide dead links for good.
- A GET is cut off after 16 kB, so a link to a large file costs no more than that. An error page is read up to 1 MB, so that its headers (a bot wall's mark, a Retry-After) are kept.
Fixing links
Under each address: Edit address, Unlink, Check again, Ignore, and for redirected links Use the new address. A change is made in every place the address is written, by rewriting that one attribute. No other attribute or text is touched, though WordPress may write the tag back in its usual form (double quotes, lower-case names). An address written in a few thousand places is changed in short steps: the message says how many places are done, and the rest goes on in the background if you leave the page.
Before a post or page is changed, Linkamend saves its content as a revision, so the change can be undone from the editor's Revisions screen. Comments, menus, widgets, term descriptions and content types without revisions, such as WooCommerce products, have no undo in WordPress. Take a backup or export the list first if you want one.
The free edition lists links on pages built with Elementor, Beaver Builder or SiteOrigin, but does not change them there: such a builder keeps its own copy of the page and would put the old link back. Linkamend says so, and you change the link in the builder. Pro changes the builder's own copy.
You can only change content you are allowed to edit. Places you may not edit are left alone and counted in the message. An Unlink removes the link and keeps the text. A link in a menu, or the address of an image, cannot be unlinked here, and Linkamend says so and tells you to change it by hand.
Comments and term descriptions are saved through WordPress's own functions, which apply WordPress's usual clean-up of markup to them.
Pro features
- Page builders. Elementor, Beaver Builder and SiteOrigin keep a page in a custom field. Pro reads it, writes fixes back to it, and clears the builder's cached output. For Beaver Builder the unpublished draft is updated as well.
- Shortcode attributes. Attributes named like an address (url, link, href, src, and names that end in them) are read, including the packed link format of WPBakery. This is a general rule. It was tested on shortcodes we wrote, not against WPBakery or Divi, which are not free to install.
- Custom fields. Name the fields under Settings. A field may hold an address, text with links, or structured data. The address of a WooCommerce external product (its Buy button) is read without naming it.
- Bulk fixes. Tick links, choose Unlink or Use the new address. Only the ticked rows on the page are changed. Use the new address leaves alone a link that now leads to a front page or to another site, because that often means the page is gone. Use Edit address on it if you are sure.
- Change the start of many addresses. Under Tools. For a site that moved, or http to https. It handles up to 5,000 addresses at a time, in short steps.
- Redirects. For a dead page on your own site that others still link to. One lookup, and only when WordPress has already found nothing at the address.
- Archived copies. For a broken link to another site, Find an archived copy asks the Internet Archive. It runs only when you press it.
- CSV export of the list you are looking at, up to 5,000 rows.
What is sent where
| To | What | When |
|---|---|---|
| Each site you link to | A request for the linked address, with Linkamend's User-Agent. No cookies, no address of your site. | When that link is checked |
| YouTube | A lookup of the video's address | When a YouTube link is checked |
| Internet Archive (Pro) | The address of one dead page | Only when you press Find an archived copy |
| Linkamend licence service (Pro) | Your licence key, your site's address, the plugin version | When you activate, deactivate or move the licence, about once a week after that (from the background schedule, or when an administrator opens the WordPress admin), when an update is downloaded, and when you delete the plugin (to free the site's place on the licence) |
| Linkamend site (Pro) | A request for a small public file with the latest version number, with Linkamend's own User-Agent. Nothing about your site. | When WordPress looks for plugin updates |
The free edition sends nothing to us at all. Neither edition sends your content, your list of links or anything about your visitors anywhere.
Multisite
On a network, each site has its own list, settings and schedule. Activate Linkamend for the whole network or site by site. A new site gets its tables when it is created, and a deleted site takes them with it. A Pro licence counts the network as one installation.
Command line
wp linkamend status, wp linkamend scan, wp linkamend check --seconds=120, wp linkamend list --status=broken --format=csv.
Removing it
Deactivating stops the background job and keeps your data. Deleting the plugin removes its three tables, its settings and its schedule, on every site of a network. Tick "Keep the list of links" under Settings first if you want the data to stay.
How it was tested
Version 1.0.0 was run against real WordPress installations on a test machine, not against mocks:
- WordPress 7.1.4 (the current release) and 6.2.15 (the oldest Linkamend supports), each on PHP 7.4 and 8.3. Single sites and multisite networks. The block editor, the classic editor, and the free editions of Elementor, Beaver Builder and SiteOrigin Page Builder.
- Eight installations in all, with the free edition and with Pro. On each, a suite of 421 to 549 checks runs inside WordPress, and 219 checks over HTTP try every button and request as a visitor, a subscriber, an editor and an administrator with a wrong or missing security token. Nothing got through, and Linkamend wrote no PHP warning or notice to the debug log.
- The links point at a small web of test sites that answer in every way we know: dead, gone, moved, moved to the front page, temporary redirects, redirect loops, slow, blocked by bot protection, rate limited, server errors, refusing HEAD, anchors, media, relative and protocol-relative addresses, and addresses with non-ASCII characters.
- A script walks the whole path a site owner takes, in Chromium, Firefox and WebKit (Safari's engine), on a desktop screen and a phone screen: upload, activate, the first pass, every kind of fix, settings, the licence, the Pro tools, then deactivate and delete. The links, settings and licence screens are also checked with axe for accessibility faults (WCAG 2.1 A and AA). After delete, nothing of Linkamend is left in the database.
- A site with 5,000 posts, 2,000 comments and 55,000 links to 21,000 addresses, on both WordPress versions: the public pages answered in 50 to 70 ms (median) before checking and no slower while checking ran back to back. Reading all content took about 13 seconds of work and 62 to 77 MB of memory. Linkamend's tables took 17 to 18 MB next to the site's own 16 MB. Two requests to the same site were never closer than the pause allows.
- The same background batch run with a cheap host's limits, 64 MB of memory and 30 seconds per request: each batch shortened itself to about 7 seconds and used at most 58 MB of the 64 allowed.
- A public page costs no extra database query with either edition active, measured by counting the queries WordPress makes.
The test machine runs PHP's own web server and MariaDB. Nothing has been tested yet on a real hosting company's servers.
What we know is weak
- It is new. Version 1.0.0 has no users yet, so no site outside our tests has run it.
- The first check of a large site is slow on purpose. At the normal pace a batch checks about 100 links, so 21,000 addresses take about 18 hours of background work, longer on a host with a 30-second limit, and longer still on a quiet site where WP-Cron only runs when someone visits. Keeping the Linkamend page open speeds it up.
- A page behind bot protection is never verified. If it is really gone, it stays under "could not verify" and is not mailed to you as broken.
- WPBakery, Divi, Oxygen, Bricks and the paid editions of Elementor and Beaver Builder are not tested, because they are not free to install. Links in shortcode attributes are read by a general rule.
- PHP 8.4 and 8.5, and the WordPress versions between 6.2 and 7.1, are not tested one by one.
- A link in a menu and the address of an image cannot be unlinked from the list. Linkamend says so and you edit them by hand.
- A server that answers HEAD with "fine" but serves an error page to a browser is reported as working. Asking for every page in full would cost the other sites far more.
- A link that redirects in a circle is listed under "could not verify", not as broken, because some sites do that only to clients without cookies.
- When this site cannot reach most other sites, failures to connect are held back for up to three days. A link that really died in that time is listed later than it could be. After three days they count again, so if the outage lasts longer, working links can be listed, and mailed in the digest, as broken. The screen and the digest say so when that happens.
- Some false alarms remain possible. If this site's name lookup (DNS) fails for some names only, those sites look exactly like domains that no longer exist, and are listed as broken after two failures. A firewall that happens to let two of the three sites Linkamend asks through is taken for a working connection. Sites are told apart by the last two parts of their name, so sites under one country domain such as .co.uk count as one, and when every site asked is under that domain, a failure counts without the check.
- On a new site there is nothing to compare with until some links to other sites have worked, so failures during an outage in the first checks count as they come (still only "failed once" until a second failure half an hour later).
- The cut-off after 16 kB works through cURL, which nearly every host has. On a server without cURL, WordPress reads the whole answer until the timeout.
- The plugin is in English only. A translation template is included.
- The Pro licence check is honest code under the GPL. Anyone can remove it from their own copy, and we do not try to stop that.