Webmentions for Jekyll

Bad URI Policy

Attempts to send webmentions to a given site may fail for a few different reasons:

  1. The site doesn’t support webmentions.
  2. The site returned an error indicating an issue with the request.
  3. The site returned a server error or there was a network connectivity issue.

When an error like this occurs, this plugin tracks a record indicating the affected host, the time the attempt was made, and the number of attempts that have been made with that host. The next time the plugin attempts to send a webmention, a configurable policy controls whether the attempt is made or skipped. This reduces the number of unnecessary attempts made when persistent error conditions are encountered.

To provide the most flexibility the plugin allows different rules to be applied depending on the type of failure encountered. The following is an example of complete retry policy:

  unsupported: ban
    policy: ignore
    policy: retry
    retry_delay: [ 1, 12, 48, 120 ]
    max_retries: 5
    - "^https://brid.gy/publish/"
    - "^https://en.wikipedia.org/"

Policy definition

As illustrated in the previous example, the retry policy is broken into sections based on the error type in question. Valid error types are:

The policy field indicates how to treat the link based on the previous error encountered:

The retry policy then allows the user to control when and how often to retry, and supports the following settings:

Whitelisting and Blacklisting

In some cases it’s desirable to force the plugin to always (or never) send a webmention to a given URL.

As a practical example, the brid.gy landing page does not publish webmention endpoints. However, the service does provide specific webmention publishing endpoints. Unfortunately, simply including the link to brid.gy in a blog post would then result in its publishing endpoints being affected (as the policy is applied to the whole host).

To support these use cases, the plugin supports these settings:

Note, the pattern is matched against the whole URI and not just the host.


The default policy is:

  default: retry

This is equivalent to infinite retries with a 24 delay.


In previous versions of this plugin the setting cache_bad_uris_for was used to control the behaviour of this plugin when an error occurred sending a webmention. As per the previous documentation:

In order to reduce unnecessary requests to servers that aren’t responding, this gem will keep track of them and avoid making new requests to them for 1 day. If you’d like to adjust this up or down, you can use this configuration value. It expects a number corresponding to the number of days you want to wait before trying the domain again.

For backward compatibility, this setting is still supported. When configured, it sets the default retry_delay value when the value is not specified in a given policy. For example, this configuration:

cache_bad_uris_for: 5
    policy: retry
    max_attempts: 5

Will result in a retry policy that waits 5 days between attempts, and stops retrying after 5 attempts.