Configuring Handshake Top-Level Domains for GitHub Pages

A Quick Start Guide for DWeb Hosting

Anthony Mandelli
4 min readAug 14, 2020


Let’s set up a sweet custom domain

What is Handshake?

Handshake is a decentralized DNS and certificate authority — think Internet Corporation for Assigned Names and Numbers but with smart contracts instead of people.

If you’re not familiar with ICANN, it’s a United States nonprofit organization that maintains databases of namespaces and numerical designations on the web; a phone book for the entire internet.

Handshake aims to experiment with new ways the internet can be more secure, resilient, and socially useful with a peer-to-peer system validated by the network’s participants. —

Handshake’s purpose is to remove the need for authorities like ICANN and the registrars that charge rental fees for domain name “ownership.” Instead, Handshake’s permissionless blockchain serves as the source of truth, providing immutable DNS records. This is the coolest part: this means when you buy a domain with Handshake, you actually own it.

Once you own a top level domain, naturally you want to do something with it. Here’s how to initially set up a personal website using GitHub Pages and then point your Handshake domain to it.

If you don’t own a Handshake domain yet, the Namebase docs walk you through the process.

Setting up a GitHub pages site

GitHub Pages lets users turn repositories into websites. There are two kinds of Pages sites: personal and project. Project sites let you turn a specific folder or branch of your repository into a website whereas personal sites require the entire repo and publish from the main branch. This guide is based on a personal GitHub Pages site.

GitHub’s official docs are very helpful; I wrote a step-by-step guide for building a Pages site as well.

Broadly speaking:

  1. Create a new repository on Github called where USERNAME is your GitHub username.
  2. Go to the repository settings…

3. …then scroll down to enable GitHub Pages by choosing a publishing source (for personal websites, select Master) and choosing a theme.

4. Add an index.html file to your repository’s root directory and commit it to your publishing source (which should be the main branch).

Updating your GitHub Pages URL settings

Once your repository has GitHub Pages enabled, in the Settings tab you’ll now have the option to set a custom domain for your site. As far as GitHub is concerned, it really is as easy as just typing in your Handshake domain and hitting ‘Save.’

I chose to set my URL as writtenby.mandelliant but it could have just as easily been mandelliant.

Configuring your Handshake top level domain

Using Namebase, from your dashboard you can manage any domains you own.

Select the domain you want to use and click the ‘Manage’ button.

If you have the ability to host your own nameservers, Namebase recommends doing so, otherwise they give you the information you need to use theirs.

Create your NS record:

Add your nameserver DNS records:

The Name field is the subdomain for your website, and the Value/Data field is where the URL should point. I left the default TTL value.

Your GitHub Pages site should now be accessible from subdomain.yourdomain/!

Visiting Handshake domains

There are two ways to see your new domain in action: changing the DNS settings on your browser/device, or using the Handshake search engine

Give a try by searching for welcome.nb or (shameless plug) writtenby.mandelliant.

gif courtesy of the Namebase docs

If you want to try modifying your DNS settings, Namebase covers a variety of methods on different platforms / operating systems.

Happy building! If you want to learn more about what’s to come for the DWeb go here:

More Handshake Educational References:



Anthony Mandelli

Technology story teller | Amateur Django dev | Blockchain, cryptocurrencies, and books.