---
title: "Add a Custom Domain"
description: "Serve your documentation from a custom domain instead of *.github.io."
tags: [Deployment, Configuration]
---

# Add a Custom Domain

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):

```{.default filename="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](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site) 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](../user-guide/deployment.html) page in the User Guide.
