Add a Custom Domain

Serve your documentation from a custom domain instead of *.github.io.

By default, GitHub Pages publishes your site at https://<username>.github.io/<repo>/. If you own a custom domain, you can point it at your documentation site so visitors access it at a cleaner URL like https://docs.example.com.

Step 1: Add a CNAME File

Create a CNAME file in your project root containing your custom domain (just the domain, no protocol):

CNAME
docs.example.com

Great Docs copies this file into the build output during great-docs build, so GitHub Pages will recognize it automatically.

Step 2: Configure DNS

Add a DNS record with your domain registrar. The record type depends on whether you are using a subdomain or an apex domain.

For a subdomain like docs.example.com, add a CNAME record:

Type Name Value
CNAME docs <username>.github.io

For an apex domain like example.com, add A records pointing to GitHub’s IP addresses. Check GitHub’s documentation for the current set of IP addresses, as they may change over time.

Step 3: Enable in GitHub Settings

After the DNS changes propagate (which can take up to 24 hours, though it is often much faster):

  1. Go to your repository’s Settings page
  2. Navigate to Pages
  3. Enter your custom domain in the “Custom domain” field
  4. Check “Enforce HTTPS” once the certificate is provisioned

GitHub automatically provisions a free TLS certificate through Let’s Encrypt. The certificate is issued after GitHub verifies your DNS configuration.

Verify Everything Works

Once the DNS has propagated and the certificate is active, your site should be accessible at your custom domain with HTTPS. The old *.github.io URL will redirect to your custom domain automatically.

If the site does not load, check the following: make sure the CNAME file was included in the build output (look for it in great-docs/_site/CNAME), verify the DNS record is correct using a tool like dig docs.example.com, and confirm the GitHub Pages section in your repository settings shows the custom domain as active.

For more deployment options and troubleshooting, see the Deployment page in the User Guide.