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!
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:
- Create a folder in the root of your site called
.well-known
- Inside that folder, create a file called
webfinger
, with no file extension - Insided that file, paste the JSON response from the WebFinger endpoint
- 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.
Comments
You can use your Mastodon account to comment on this post. Learn how this is implemeted here.
Reply via Mastodon
Load comments from Mastodon