This guide will walk you through the process of serving a static page on a subdomain using GitHub Pages. Follow these steps to correctly configure your project and DNS settings.

1. Configuration

First, ensure your next.config.mjs file is set up for static export:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export",
  };

This configuration tells Next.js to generate static files for your project.

2. Set Up CNAME File

Create a file named CNAME in your project's root directory (or in the /out folder for Next.js projects). The file should contain only your subdomain:

sub.domain.com

Replace sub.domain.com with your actual subdomain.

3. Configure GitHub Pages Settings

Go to your GitHub repository.
Navigate to Settings > Pages.
Under "Custom domain", enter your subdomain (You may skip this. This table will be filled in automatically if step 2 done.)
Save the changes and wait for GitHub to provision an HTTPS certificate for your subdomain.

4. Set Up DNS Records

Configure your DNS settings to point your subdomain to GitHub Pages. Add the following A records:

sub.domain.com A 185.199.108.153
sub.domain.com A 185.199.109.153
sub.domain.com A 185.199.110.153
sub.domain.com A 185.199.111.153

If you're also using GitHub Pages for your root domain, keep these A records:

# origin (keep it)
@ A 185.199.108.153
@ A 185.199.109.153
@ A 185.199.110.153
@ A 185.199.111.153

Important Note

While GitHub can serve your subdomain page, it does not allow direct access via:

sub.youraccount.github.io

This URL format is not supported for subdomains on GitHub Pages. By following these steps, you’ll successfully set up a subdomain for your static page hosted on GitHub Pages. Remember to allow some time for DNS changes to propagate and for GitHub to set up HTTPS for your subdomain.

The below secions will show some message like this:

TLS certificate is being provisioned.
This may take up to 15 minutes to complete.
1 of 3....
Certificate Requested: This domain was recently added.
The certificate request process will begin shortly.

Seeing a DNS check unsuccessful message? You might think it failed, but if the link still works, just ignore that message. ALL GOOD!