{linkcheck:url:format}

Description

Checks whether a URL is reachable and returns its HTTP status, formatted however you like. linkcheck makes a live request to the address (a HEAD, falling back to GET), follows redirects, and reports the result. With only a url it returns the status code, such as 200. A second format parameter is a template in which aliases are replaced with that link's values: _#code (status code), _#text (status comment like OK or Not Found), _#weight (severity from 0 healthy to 5 broken), _#color (a matching hex colour), _#span (a ready-made coloured badge), _#redir (final URL after redirects), _#hops (number of redirects), _#mime and _#charset (content type), and _#duration (seconds taken). mailto: addresses are checked for a valid mail domain - write the colon as mailto#: so it is not read as a parameter separator. The result is never cached, since it reflects the link's state right now.

Parameters

url required default (none - required)

The address to check. Must start with http:// or https:// (it is fetched with a real HEAD/GET request). A mailto: address is also accepted, but its colon collides with the parameter separator, so write it as mailto#: - linkcheck then verifies the domain has a mail (MX) record. Any other scheme (ftp:, tel:, ...) is reported as Non HTTP. An empty url makes the whole expression return an empty string.

format optional default _#code

A template for the output. Any of these aliases that appear in it are replaced with that link's values, and surrounding text is kept as written: _#code (HTTP status code, e.g. 200), _#text (status comment, e.g. OK or Not Found), _#weight (severity 0 healthy to 5 broken), _#color (a hex colour matching the weight, green to red), _#span (a ready-made coloured HTML badge built from color/text/code), _#redir (final URL after following redirects), _#hops (number of redirects, empty if none), _#mime (MIME type from Content-Type), _#charset (charset if the server sends one), _#duration (seconds the check took). With no format the default is _#code.

Examples

virtual{linkcheck:https://example.com/}

Expected200 (live check; depends on the target server)

Actual200

Default format. With no second parameter the result is _#code, the HTTP status code the URL returned. A reachable page gives 200. The check is a live network request, so the value depends on the target server at the moment of rendering.

virtual{linkcheck:https://example.com/:_#text}

ExpectedOK (live check; depends on the target server)

ActualOK

The format _#text returns the status comment instead of the bare code. For 200 this install prints OK; a missing page would print Not Found.

virtual{linkcheck:https://example.com/:_#weight}

Expected0 (live check; depends on the target server)

Actual0

The format _#weight returns a severity from 0 (healthy: 2xx) to 5 (broken: most 4xx/5xx, no response). Redirects and soft problems fall in between. Useful for sorting or flagging links by health.

virtual{linkcheck:https://example.com/:_#span}

Expected200 (live check)

200 (live check)">Actual200

The shorthand _#span expands to a ready-made HTML badge: a span whose background-color comes from _#color (green for healthy, red for broken), whose title tooltip is _#text, and whose label is _#code. Drop it next to a link to show its health at a glance.

virtual{linkcheck:https://example.com/:_#code _#text (weight _#weight)}

Expected200 OK (weight 0) (live check)

Actual200 OK (weight 0)

The format is a free template. Any of the aliases _#code, _#text, _#weight, _#color, _#redir, _#hops, _#mime, _#charset, _#duration that appear in it are replaced with that link's values; surrounding text is kept as written.

virtual{linkcheck:https://example.com/:_#mime}

Expectedtext/html (live check; depends on the target server)

Actualtext/html

The format _#mime returns the MIME type from the response Content-Type header (here text/html). _#charset returns the charset when the server sends one, otherwise empty.

virtual{linkcheck:https://example.com/this-page-does-not-exist:_#code _#text}

Expected404 Not Found (live check; depends on the target server)

Actual404 Not Found

A URL that resolves but has no such page returns the server's error status. A missing page typically gives 404 Not Found (weight 5).

virtual{linkcheck:http://www.actionapps.org/:_#code _#text}

Expected301 Moved Permanently - Redirected [200] (live check)

Actual301 Moved Permanently - Redirected [200]

linkcheck follows redirects. _#code is the FIRST hop's status (e.g. 301) and the comment is suffixed with the final code reached, like " - Redirected [200]". _#redir holds the final URL and _#hops the number of redirects.

virtual{linkcheck:mailto#:test@example.com:_#text}

ExpectedValid hostname (live check; depends on DNS)

ActualValid hostname

A mailto: link's own colon collides with the colon that separates linkcheck's parameters. Escape it as mailto#: so the whole address stays in the url parameter; then linkcheck verifies the domain has a mail (MX) record. A valid hostname prints Valid hostname (weight 0); an unresolvable one prints Invalid hostname (weight 5). Written without the escape, {linkcheck#:mailto#:you@x.org} would mis-split and treat test@example.com as the format.

← All expressions