If you're setting up a custom domain for your GitHub Pages site, choose a supported custom domain for the easiest setup and more support. GitHub Pages is designed to work with two types of custom domains: apex domains and subdomains.

In this article:

We recommend choosing a supported custom domain because unsupported custom domains are not guaranteed to work and may require a domain forwarding service or extra setup with your DNS provider.

These supported custom domains are optimized for GitHub Pages. The most recommended custom domain types are bold.

Supported custom domain type Example domain
www subdomain www.example.com
one apex domain & one www subdomain example.com & www.example.com
apex domain example.com
custom subdomain blog.example.com

Tip: We recommend using a www subdomain as your custom domain. If you choose to use an apex domain as your custom domain then we recommend setting up a www subdomain as well. To learn why, see "www subdomains"

Subdomains

The term subdomain has two common meanings:

  1. A customizable and optional part of a domain name located before the root or apex domain that looks like a domain prefix.

  2. A type of domain that contains a subdomain part.

To avoid confusion, custom domains with different subdomain parts are assigned different labels. A custom domain without a subdomain part, such as example.com, is called an apex domain.

Subdomain Subdomain part Subdomain type
www.example.com www www subdomain
blog.example.com blog custom subdomain

www subdomains

A www subdomain is the most commonly used type of subdomain, in which the www stands for World Wide Web. For example, www.example.com is a www subdomain because it contains the subdomain part www.

We strongly recommend that you use a www subdomain for these reasons:

  • It gives your GitHub Pages site the benefit of our Content Delivery Network.
  • It is more stable because it is not affected by changes to the IP addresses of GitHub's servers.
  • Pages will load significantly faster because Denial of Service attack protection can be implemented more efficiently.

Custom subdomains

A custom subdomain is a type of subdomain that doesn't use the standard www subdomain part. It is commonly used to manage different host locations or computer servers. For example, blog in blog.example.io may be hosted on a different computer server than www.example.io or photos.example.io. GitHub Pages supports one custom subdomain per pages site.

Setting up subdomains

A subdomain is configured with a CNAME record through your DNS provider.

To learn more about setting up a subdomain, see one of these articles:

Apex domains

An apex domain is a root domain that does not contain a subdomain part. Apex domains are also known as base, bare, naked, root apex, or zone apex domains. In DNS provider settings apex domains are sometimes symbolized by an @ symbol. For example:

  • example.com is an apex domain because it doesn't have any subdomain parts.
  • Whereas www.example.com is not an apex domain because it contains the subdomain part www.

Setting up apex domains

An apex domain is usually configured with an A, ALIAS, or ANAME record through your DNS provider.

To learn more about setting up an apex domain, see one of these articles:

Tip: If you are using an apex domain as your custom domain, we recommend setting up a www subdomain as well. To learn more, see "Setting up an apex domain and www subdomain."

Further reading