Skip to main content

Pelican plugin implementing Linkback protocols, on the linking server side

Project description

Pull Requests Welcome build status Pypi latest version License: AGPL v3

Pelican plugin implementing Linkback protocols, on the linking server side.

Protocols currently implemented:

❌ Refback: won't be implemented because it requires to retrieve the HTTP Referer header, which cannot be done by Pelican, a static blog engine

❌ TalkBack: won't be implemented because it did not gain enough popularity / traction since its birth in 2011

❌ Trackback (protocol spec): won't be implemented because it does not seem widely used, and requires to parse embedded RDF documents (enclosed in HTML comments as a fallback), which seems a poor design in an era of HTML5 / RDFa

Do not hesitate to suggest other protocols, or report your experience with this plugin, by submitting an issue.

What are linkbacks?

A linkback is a method for Web authors to obtain notifications when other authors link to one of their documents. This enables authors to keep track of who is linking to, or referring to, their articles. The four methods (Refback, Trackback, Pingback and Webmention) differ in how they accomplish this task.

I invite you to read this Wikipedia page for more information & links: Linkback

What does this plugin do?

For every hyperlink in your articles, this plugin will notify their hosting websites (just those supporting a Linkback protocol) of those references.

This plugin does not perform inclusion of Linkbacks in your articles / as comments, for every website referencing your content following a Linkback protocol, because this cannot be performed by a static website generator like Pelican.

When you enable this plugin the first time, it will process all the hyperlinks of your existing articles. It will do it only once, and then create a cache file to avoid processing those links next time. Still, because the publish step will be longer than usual the first time you enable this plugin, I recommend to use pelican -D flag to get debug logs, and hence follow the plugin progress.

Installation / setup instructions

To enable this plugin, git clone this repository and add the following to your publishconf.py:

PLUGIN_PATH = 'path/to/this-repo'
PLUGINS = ['linkbacks', ...]

PLUGIN_PATH can be a path relative to your settings file or an absolute path.

You will also need to install the Pypi dependencies listed in pyproject.toml:

pip install poetry
poetry install

Cache

In order to avoid the repetitive CPU / bandwidth cost of repeatedly performing links parsing & linkback notifications, this hook only proceed to do so once, the first time an article is published.

In order to do so, it uses a very simple and small cache that contains the list of all hyperlinks already parsed, per article slug.

Configuration

Available options:

  • LINKBACKS_CACHEPATH (optional, default: $CACHE_PATH/pelican-plugin-linkbacks.json, where $CACHE_PATH is a Pelican setting) : the path to the JSON file containg this plugin cache (a list of URLs already processed).
  • LINKBACKS_USERAGENT (optional, default: pelican-plugin-linkbacks) : the User-Agent HTTP header to use while sending notifications.

Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.

To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.

Releasing a new version

With a valid ~/.pypirc:

  1. update CHANGELOG.md
  2. bump version in pyproject.toml
  3. poetry build && poetry publish
  4. perform a release on GitGub, including the description added to CHANGELOG.md

Linter & tests

To execute them:

pylint *linkbacks.py
pytest

Integration tests

You'll find some advices & resources on indieweb.org: pingback page, webmention page.

For WebMentions specifically, the webmention.io service can be useful.

For Pingbacks, I used for my tests a Wordpress instance launched with Docker:

docker run --rm -p 80:80 -e WORDPRESS_DB_HOST=host.docker.internal -e WORDPRESS_DB_USER=... -e WORDPRESS_DB_PASSWORD=... wordpress

From my experience, you'll also have to:

  • configure a local MySQL database to accept connections from $WORDPRESS_DB_USER:$WORDPRESS_DB_PASSWORD
  • configure the xmlrpc_pingback_error Wordpress filter to be passthrough, to get useful error messages
  • configure the http_request_host_is_external Wordpress filter to always return true, so that it won't reject host.docker.internal links

And there is Wordpress client source code related to XML-RPC pingbacks:

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pelican-plugin-linkbacks, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size pelican_plugin_linkbacks-1.0.0-py3-none-any.whl (22.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pelican-plugin-linkbacks-1.0.0.tar.gz (20.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page