Put your site online
on a domain you own.

The finished setup has four moving parts. Each one is handled in a step below.

Three files, three consumers

Before you touch anything, it helps to know who reads each piece. Different software looks at a different one, and that is why a setup can look complete and still serve nothing.

What you need

• A GitHub account (free)
• A domain whose DNS you can edit — this guide uses a web3 domain, and section 05 covers what makes those different
• About twenty-five minutes

Make a folder called mysite and put these inside. This very page is built exactly this way.

mysite/
├── index.html      the page itself (required)
├── favicon.svg     the little tab icon
├── .nojekyll       empty file - see below
├── images/         optional, only if your site uses one
└── CNAME           added in step 04, your domain only

Every one of these sits at the top level of the folder. That is not a style preference — put index.html inside a subfolder and the site 404s, and you’ll see it happen in step 06.

index.html

GitHub Pages serves index.html at the root automatically. This one keeps everything inline — no separate stylesheet, no JavaScript, nothing to break.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My site</title>
  <style>
    body { font-family: system-ui; margin: 0; }
    .wrap { max-width: 900px; margin: auto; padding: 24px; }
  </style>
</head>
<body>
  <div class="wrap">
    <h1>It works.</h1>
    <p>Served from GitHub Pages.</p>
  </div>
</body>
</html>

The .nojekyll file

Create a completely empty file called .nojekyll, with no extension and nothing inside it. GitHub runs Pages through a system called Jekyll, and Jekyll silently skips any folder whose name starts with an underscore. This file turns Jekyll off so every file and folder you commit gets published exactly as-is.

Create it

Go to github.com/new and fill in the form.

1. 1Open github.com/new.
2. 2Give the repository a name. Your Pages address will be username.github.io/this name/, so pick something you can live with in a link.
3. 3The Description is optional and appears on the repo’s front page. Write whatever you like.
4. 4Visibility — choose Public. Pages on a private repository is a paid feature, and this is the setting people most often leave on the wrong value.
5. 5Add README — leave it off. This guide has you upload your own index.html below, and a README here just adds a file you don’t need.
6. 6Add .gitignore — leave it as No .gitignore. The template picks a language for you, and for a plain static site there’s nothing to ignore.
7. 7Add license — No license is fine unless you intend to publish source others reuse.
8. 8Click Create repository.

Upload

Open the empty repo, then drag your files in — or click Add file → Upload files and drop them there. Scroll down and Commit changes.

1. 1Your repo’s address: github.com/yourusername/yourreponame.
2. 2Any images folder, if your site uses one. Entirely optional — a site with no images simply won’t have it.
3. 3.nojekyll. Empty, no extension. Without it, files can silently vanish from the published site — see step 01.
4. 4CNAME, added in step 04. Ignore it for now; you can add it later without disturbing anything else.
5. 5index.html. This must be the one that gets served.

Or use the command line

Faster once you’re past the first commit, and you get proper history:

git init -b main
git add .
git commit -m "Add site"
git remote add origin https://github.com/username/repo.git
git push -u origin main

In your repo open Settings → Pages.

1. 1Open github.com/yourusername/yourrepo/settings/pages.
2. 2Set Source to Deploy from a branch.
3. 3Branch main, folder / (root), then Save.
4. 4Paste your domain into Custom domain and Save. Then ignore the red “DNS check unsuccessful” warning underneath it.
5. 5Enforce HTTPS — leave it unchecked. Web3 domains are HTTP-only on Noto DNS, so no certificate can ever be issued for one. GitHub greys this out for exactly that reason.
6. 6Your domain appears in the green box: “Your site is live at”. This is the only thing that proves it worked. Before you add a custom domain, this box shows your github.io address instead.

Two pieces of setup, and the order matters.

4a — add the CNAME file

This one small file is what connects your domain to your repo. Saving the custom domain in step 03 usually creates it for you, so open your repo and look first. If CNAME is there, holding one line — your domain — and nothing else, you can skip to 4b. If it isn’t, make it by hand: a file named exactly CNAME containing one line, with no quotes, no slash and no trailing dot.

yourdomain.virtualsociety

Adding it through the browser

1. Open your repo on GitHub, click Add file → Create new file
2. In the name box type CNAME — exactly that, all capitals, no extension
3. Paste your domain into the content box below
4. Scroll down and Commit changes
5. Wait a minute, reload Settings → Pages — the Custom domain box fills itself in

Adding it from the command line

echo "yourdomain.virtualsociety" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push

4b — the DNS records

Add these on your domain’s Records tab. Only the first is required:

GitHub Pages publishes on four anycast addresses, so you will see guides telling you to add all four. We tested it: one is enough. Add the extra three and your site still serves identically. We carry a single A record, and it has been stable.

1. 1Open your domain, then the Records tab. The status line under the domain name should read “resolves” — if it doesn’t yet, you’re looking at a name with nothing published, which is normal before step 05.
2. 2Wallet Address plus the yellow Sign Transaction button. This button is what actually commits your records to the chain. Everything below is only configuration until you press it.
3. 3Forward Domain — the trap. Its own caption on screen says it “will disable your root A record pointing to 185.199.108.153”. Leave it off.
4. 4In DNS Records, add a single A row on @ with value 185.199.108.153, TTL 300. The two NS rows are added for you — leave them.
5. 5Optional: a CNAME row on www pointing at yourusername.github.io. Your bare domain works without it; this just makes www behave the same way.
6. 6In Web3 Records, add record.A.0 — lower-case record, capital A — with the same IP, 185.199.108.153. This on-chain slot is what the nameserver reads.
7. 7Also in Web3 Records, add redirect.WEBSITE.0 — lower-case redirect, capital WEBSITE — with your Pages URL, https://yourusername.github.io/yourrepo/. Note it points at the github.io address, not at your web3 domain.

On a web3 domain your records live on a blockchain, and the nameserver reads them from there. That changes two things, and both surprise people badly.

It looks right but isn’t

The dashboard will happily save a record, display it back to you in a tidy table, and every field will look perfect — while your domain points somewhere else entirely. Saving is not publishing. Until the record reaches the chain, the nameserver has nothing to serve.

Two records, not six

GitHub Pages publishes on four IP addresses, and most guides tell you to fill four on-chain slots. We tested it. One is enough. Add .0 and leave .1, .2 and .3 empty — the site keeps serving perfectly in every browser that reads the record. Fewer records, fewer things to go wrong.

Then sign it

Near the top of the same Records tab there’s a Wallet Address box with a Sign Transaction button. That button is what commits your saved records to the chain. Until you press it, you have configuration, not a live domain.

Good news first: you have two ways to open the finished site, and only one of them needs any web3 tooling at all.

The easy check — your web2 link

Every .virtualsociety name is automatically mirrored onto the ordinary web at yourname.virtualsociety.top. You don’t configure this, don’t pay for it, and don’t set anything up for it — it exists as soon as your domain resolves. It opens in any browser, no plugin, no API key, and over HTTPS.

1. 1Go to virtualsociety.top/getweb2link.
2. 2Type the web3 name you registered on .virtualsociety and press Resolve.
3. 3You get back your mirrored web2 link — https://yourname.virtualsociety.top/.
4. 4Your site is previewed right there in the page. If it renders, everything upstream already works.
5. 5Click the link to open your site on the web2 address — this is the same action as number 3 above, it just also opens it.
6. 6Top right: your web2 link open on its own, in a normal browser, over HTTPS.
7. 7Bottom right: the same site on the web3 address, yourname.virtualsociety. Identical page. This one needs Noto DNS or a web3 browser — the web2 one above doesn’t.

The authoritative check — what your domain publishes

To confirm the records themselves, use the DNS tool. This reads straight from Freename’s own nameservers, so it shows you the truth rather than a cache.

1. 1Go to virtualsociety.top/tool/dnscheck.
2. 2Type your web3 name and press Look up.
3. 3You get your published records. The A row should read 185.199.108.153, with NS 1 and NS 2 showing the Noto nameservers. AAAA, MX and TXT showing none published is perfectly normal. CNAME is empty unless you added the optional www row in step 04 — both states are correct.

The command line

Two commands, because they answer two different questions. The first asks “where does my domain point?” The second asks “is anything actually being served there?” Running both tells you which half is broken.

nslookup yourdomain.virtualsociety ns1.noto.network

You want to see 185.199.108.153.

curl -H "Host: yourdomain.virtualsociety" http://185.199.108.153/

You want to see your own HTML.

Then read the result