If you are like myself and many other Birdsite users of past, you have began flocking to Mastodon and making yourself a home there. Mastodon although is different than most mainstream social media platforms. It is a federated network, meaning that there are many different instances of Mastodon that are all connected to each other. This means that you can choose which instance you want to use and you can even create your own instance if you want to. This is great because it means that you can choose an instance that you like and that you feel comfortable with.

So you decided to choose an instance you liked and created an account. In my case, I chose to use iosdev.space as my instance and my username is kylewritescode. Therefore, my full Mastodon account is @kylewritescode@iosdev.space.

What if you wanted to add a little more personalization to your username? What if you wanted to use a domain you already have without having to struggle with hosting an entire Mastodon server? With this personalization, it means that no matter what instance you use, or what instance you decide to use in the future, you will always be able to share the same username and have it pointed to your account.

Here is how I did it using GitHub Pages. Although, this can be done using any hosting service that allows you to create a .named folder.

Using WebFinger

Mastodon uses ActivityPub to communication with “actors” and those actors are found using WebFinger, a way to attach information to a specific email address or other online resource. So, to get my personalized username to work, I just needed to create a WebFinger spec on my domain.

<yourinstaceaddress>/.well-known/webfinger?resource=acct:<yourusername>@<yourinstaceaddress>

So, if I wanted to get information about my account on iosdev.space, I would go to:

https://iosdev.space/.well-known/webfinger?resource=acct:kylewritescode@iosdev.space

That means, when I go to that endpoint, I get a JSON response that looks like this:

{
  "subject": "acct:kylewritescode@iosdev.space",
  "aliases": [
    "https://iosdev.space/@kylewritescode",
    "https://iosdev.space/users/kylewritescode"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://iosdev.space/@kylewritescode"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://iosdev.space/users/kylewritescode"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://iosdev.space/authorize_interaction?uri={uri}"
    }
  ]
}

Now all I need to do is put that JSON reponse in the same directory and file and that’s it!

Support this site with a cup of coffee

Creating the WebFinger Spec with Jekyll

My blog runs on Jekyll and is hosted on GitHub Pages. To have your Mastodon alias work with your domain tied to your Jekyll site, you need to follow a few steps:

1. Create a folder in the root of your site called .well-known
2. Inside that folder, create a file called webfinger, with no file extension
3. Insided that file, paste the JSON response from the WebFinger endpoint
4. In your _config.yml file, add the following: (This allows Jekyll to include the .well-known folder in the build process.)

include: ["/.well-known" ]

That’s it! Just push your changes to GitHub and your alias will be ready to go. You can test it by going to anything@yourdomain.whatever on Mastodon and it will redirect you to your account.

Check it out! Here is my alias working on Mastodon:

---

References

During my research, I found out about this method thanks to the article by Maarten Balliauw called Mastodon on your own domain without hosting a server.