Skip to content

Instantly share code, notes, and snippets.

Last active December 19, 2022 17:17
What would you like to do?
how to setup mastodon forwarding from your custom domain using webfinger and github pages

how to setup mastodon forwarding from your custom domain using webfinger and github pages



say you have your own domain, cool.example, and you'd rather use very@cool.example as your identity instead of you can!


I'll assume you already have a repo setup with github pages turned on (or some other static site hosting), and that you already have a mastodon account somewhere.


mastodon, the hot new social network thing, is built on a series of open protocols. One is webfinger, a way to look up accounts like "" and figure out how to do stuff with them (like follow them on mastodon).

the "web" part of webfinger is that it returns plain json via a URL, eg https://cool.example/.well-known/webfinger?resource=very@cool.example

if we're ok using the same forwarding information for any account on the domain, we can ignore the resource query param and use a static json document as our response!


step 0 - enable publishing .well-known (only in github pages)

look for a file called _config.yaml - edit it or add it if it doesn't exist. add this to the file:

include: [".well-known"]

this let's github pages publish the files we'll add next - otherwise, they'll be ignored

step 1 - configure webfinger

add a file called /.well-known/host-meta containing:

<xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="">
  <Link rel="lrdd" template="https://cool.example/.well-known/webfinger?resource={uri}" type="application/xrd+xml" />

(replace cool.example with your domain) (this is oldschool xml - case matters! just leave it as-is)

the internet is based on 18 layers of pedantry, and this file will help increase compatibility.

step 2 - download your existing mastodon account info

in a browser tab, go to (replace in both places with your instance domain, if needed)

you should see a bunch of json. copy and paste this, as-is, into a new file in your repo, called /.well-known/webfinger.

step 3 - publish and test

make sure all 3 files in steps 0-2 are committed to your github pages repo. in a browser, check that you're able to access https://cool.example/.well-known/webfinger and that it returns your account json.

finally, go to mastodon and try searching for anything@cool.example - you should see your profile come up- voila!

if you want to see an example, check out my super basic gh pages site,

gotchas + caveats

this is like the basic email forwarding that some domain registrars offer - people can contact you at this address, but your outgoing mail will come from your actual email provider.

similarly, this method will let people search for your by your custom domain address, but your posts will appear to come from your home mastodon instance address.

if you really want the full custom domain experience, you'll have to get fancier, maybe even run your own mastodon instance - but that's outside the scope of this gist.


this gist is based heavily on this blog and this gh issue. i first got the inkling to want to do this based on this post

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment