static-webmentions

A tool to send webmentions from a static website.


The information below may be outdated. For the latest version, check the repository.

static-webmentions

a tool to send webmentions from a static website

Build Status codecov Go Report Card

Table of Contents

Help static-webmentions get better!

Join the development (or just buy me a coffee, that helps, too).

Why

Sending webmentions is relatively easy if you use a CMS. If, however, your site is built using a static site generator like Hugo, sending webmentions is not as straightforward.

This tool allows you to do just that, and with some effort you can even automate your outgoing webmentions.

How

The way static-webmentions works is by comparing two versions of a static site (residing in two separate directories), figuring out what new webmentions are to be sent, and, eventually, sending them. Thus, you need to make sure that at some point of your publishing process you have two directories: one with the old state of your site, and one with the new state. Given that you have static-webmentions configured correctly, at this point you can:

1
static-webmentions find

to find out which webmentions are to be sent and save them to a temporary file, and then, when the new content is online and alive,

1
static-webmentions send

to read the pending webmentions from the temporary file and send them out.

If your publishing process is set up so that at the moment when you have the two versions the new version is already published, you can do both steps in one go:

1
static-webmentions

static-webmention will detect new and changed pages, and send webmentions as appropriate. To have deleted pages processed correctly, the new state of the site should have tombstones containing a <meta http-equiv="Status" content="410 Gone" /> tag in place of the removed pages.

Configuration

static-webmentions will look for a config file (config.toml in current directory by default). An example config file with all the supported options is included, all the options are fairly self-explanatory. Hugo users may want to use the same config.toml that they store their website configuration in.

Several command-line flags can be used to override the options specified in the config file:

1
-c [filename]

the config file to read config from. Default is config.toml in current working directory.

1
-b [url]

base URL of the site (i.e. http://my-awesome-site.web).

1
-f [filename]

the file to store pending webmentions to, or to read them from if send command is given. If no file is specified, static-webmentions find will just print out the list of webmentions it found.

1
-o [directory] -n [directory]

the directories where old and new versions of the site are located.

Automation

Depending on your publishing process, automating your outgoing webmentions may require different steps. Here’s an example how I do it for my own website.

The website is built using Hugo, the source is stored in a Git repository. I put both hugo and static-webmentions binaries on the hosting server, and can publish a new version of the site with a simple script:

1
2
3
4
5
6
#!/bin/sh
cd /home/my-user/hugo                       # this is the folder with my website source
git pull
rsync -am --del public old                  # the current public directory is copied to old/public
hugo --gc --cleanDestinationDir -d public   # hugo puts new version in public directory
static-webmentions                          # compares public to old/public and sends webmentions

The actual script I use is more complex and the actual process is more error-proof, the script above is a minimal working example.

Development

Pull requests are always welcome!

Credits

This software includes the following software or parts thereof: