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


    CNAME


``` default
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.md) page in the User Guide.