06 Mar 2021  guides

Configuring Vanity Subdomain Redirects using Netlify

I think it’s always handy to have a vanity subdomain that does custom URL forwarding that can link to referral codes, social media handles, or any sort of valued content. I’ll walk through the steps to setup a Netlify site for this purpose — using my setup for go.paramdeo.com as a real-world example.

One benefit of using a subdomain for vanity redirects is that you can decouple it from your primary URL structure; which is good for separation of concerns and for accurately logging usage. Also, a subdomain will work even if your primary domain isn’t hosted on Netlify, since it’s stored and built from it’s own separate repository.

Create the Repository

A bit of background; Netlify looks for redirect rules in either of two files present within a site’s directory:

  1. A netlify.toml file which offers the full gamut of options for fine-tuning redirect behavior
  2. A _redirects file with simplified syntax that works out of the box

I’ll be using the second option since it covers my needs. As you might have guessed, the _redirects file is the only file we’ll actually be storing in the repository.

I created a new project in GitLab , which will hold the redirect file. Since this is a single file, I’ll just create the repo in GitLab’s web-based IDE to save time:

Below are the contents of the _redirects file:

github         https://github.com/oedmarap
mastodon       https://fosstodon.org/@oedmarap
twitter        https://twitter.com/oedmarap
instagram      https://instagram.com/oedmarap
tumblr         https://oedmarap.tumblr.com
hackernews     https://news.ycombinator.com/user?id=oedmarap
matrix         https://matrix.to/#/@oedmarap:matrix.org
telegram       https://t.me/oedmarap
digitalocean   https://m.do.co/c/172de6c6559d
bunnycdn       https://bunnycdn.com/?ref=66lg2a410o
/              https://paramdeo.com

The first string in each line represents the source URL, while the second string (tab-separated) is the target URL that the user will be redirected to. It’s pretty simple, and each redirect sits on its own new line.

Notably, the last line forwards the root of the subdomain go.paramdeo.com to the parent domain paramdeo.com so as to prevent any navigation to the subdomain directly.

Create Site in Netlify

Next, I’ll connect the repo to Netlify so that a site can be created. This is a pretty straightforward process and there are no build commands required, since there isn’t any actual HTML output:

Configure Netlify Domain

Once the site is created, I’ll change the default site name to something clearer, then connect my subdomain go.paramdeo.com to Netlify by adding a CNAME record within Cloudflare that points to the Netlify namespace:


At this point the “site” is already live. Once the domain’s CNAME resolves (takes a minute or less) I can go ahead and test it.

I visited go.paramdeo.com/mastodon and sure enough it forwarded me to my Mastodon account over at FOSStodon . You can also validate the HTTP 301 status code by using curl and the output would look like this:

If I need to add a new redirect rule, I would push commits to the origin (if I have it cloned locally) or edit the file in GitLab directly and commit changes from there (which is simpler).

Using vanity redirect URLs becomes very useful when you consider that you can edit the redirect rules in a central location, without having to update each target link across your site if the social media handle or affiliate link were to change; which is the embodiment of a functional approach.

Webmentions & Comments

Copyright © Paramdeo Singh. Built with Jekyll and ☕️ in Guyana. All Rights Reserved.

Last Site Build on Fri, 18 Jun 2021 13:00:57 -0400

1MB Club Badge

Paramdeo Singh Guyana

Riding the wave of consciousness in this treacherous mortal sea.

Technology Design Strategy Literature Personal Blogs