Using Webfinger on a static webhost to let people find you on Mastodon

Mastodon uses the Webfinger protocol to find users on a domain. Even on statically hosted websites, like GitHub Pages, you can put the configuration files in the right place to be findable per domain name.

My friend @sheean@sheean.nl tweeted about a how-to to use your own domain name on Mastodon, without running a dedicated server. That’s ideal when the website host is statically hosted, like e.g. GitHub Pages. This website is statically hosted and I have a Mastodon account, so that sounded right up my alley.

The Mastodon Guide is clear enough on the contents of the file, but for Jekyll specifically, some tweaks were needed. This post assumes regular GitHub Pages hosting using Jekyll (i.e., not the new [2022] GitHub Actions workflow-style).

  1. Save a new webfinger file anywhere in your website’s repository
    1. The filename webfinger, without an extension. Otherwise, the live file can only be accessed as webfinger.json and that’s not what the spec requires.
    2. This, unfortunately, also makes (on my machine™) that visiting rdmr.eu/.well-known/webfinger results in a downloaded file, as GitHub Pages can’t deduce the mimetype for the browser. It of course works on my Mastodon server.
    3. (The correct mimetype would come from a file served from webfinger/index.json, but that would let GitHub Pages add a slash: rdmr.eu/.well-known/webfinger/ and that’s undesireable too.)

  2. Add Jekyll front-matter to the file:

    1. Add layout: null to remove all layout markup, leaving only the contents of the webfinger file – save for the front-matter of course!

    2. Add permalink: /.well-known/webfinger so this file doesn’t need to live in that exact path in your repository. Because of the theme I use (redmer/minimaal), I put it in the /assets/ dir.

    3. That completes the file contents:
    ---
layout: null
permalink: /.well-known/webfinger
---
{
  "subject": "acct:${MASTODON_USER}@${MASTODON_DOMAIN}",
  "aliases": [
    "https://${MASTODON_DOMAIN}/@${MASTODON_USER}",
    "https://${MASTODON_DOMAIN}/users/${MASTODON_USER}"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://${MASTODON_DOMAIN}/@${MASTODON_USER}"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://${MASTODON_DOMAIN}/users/${MASTODON_USER}"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://${MASTODON_DOMAIN}/authorize_interaction?uri={uri}"
    }
  ]
}
  3. Commit, push and let the website render.

So now, if you’re logged into your Fediverse / Mastodon server, you can follow me by searching for the account @me@rdmr.eu. Thanks for doing so 🐘

With the additional nodeinfo and host-meta files, you can also make your account visible for OASIS Open and Diaspora. Just follow the additional instructions in the Mastodon Guide.