GitHub Pages

What is GitHub Pages?

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a live webpage. GitHub Pages are most commonly used for hosting open source project landing pages, documentation, blogs, personal websites, and more. This guide covers the essentials of using GitHub Pages, including setting up a site, deploying it, using a custom domain, handling private repositories, and troubleshooting common issues like the 404 error.

How to use GitHub Pages

Setting up your GitHub Pages site

1. Create a repository: If you don't already have a repository, create one on GitHub. This can be a new or existing repository. The name of the repository will dictate your project's default URL (e.g. username.github.io/repository).

2. Add your content: Add your HTML, CSS, and JavaScript files to the repository. If you're creating a project site, you can place them in the root or in a docs/ folder. For a personal or team website, you should use the root.

3. Enable GitHub Pages: Go to your repository's Pages settings at https://github.com/<REPO_OWNER>/<REPOSITORY_NAME>/settings/pages , and select the branch and folder to deploy from. GitHub will provide a URL where your site will be published.

Deploying your GitHub Pages site

After setting up your site, any push to your selected branch will automatically deploy the changes. Here's a typical workflow:

git add .
git commit -m "Update site content"
git push origin main

This will trigger a build and deploy process on GitHub, making your changes live almost immediately.

Custom domain for GitHub Pages

Configuring a custom domain for your GitHub Pages site allows you to personalize the URL of your website, enhancing its professional appearance and making it easier for visitors to remember. Here’s how you can set up a custom domain for your GitHub Pages:

Step 1: Purchase a domain

First, you need to purchase a domain from a domain registrar such as GoDaddy, Namecheap, or Google Domains.

Step 2: Configure your GitHub repository

1. Navigate to your GitHub repository where your GitHub Pages site is hosted.
2. Go to the repository settings: Find the "Settings" tab near the top of the repository page.
3. Locate the Pages section: Scroll down or use the sidebar to navigate to the "Pages" section.
4. Specify your custom domain:
   • In the "Custom domain" section, enter your purchased domain name (e.g., www.example.com) and save the changes.
   • GitHub will automatically create a CNAME file in the root of your repository if it doesn’t already exist. This file should contain the name of your custom domain.

Step 3: Configure DNS settings

After setting the custom domain in your GitHub repository, you need to update the DNS settings with your domain registrar to point to GitHub’s servers.

For an apex domain (example.com):

• A Records: Point your domain’s A records to the following IP addresses:
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

For a Subdomain (www.example.com):

• CNAME Record: Create a CNAME record pointing your subdomain to your-username.github.io (replace your-username with your actual GitHub username).

Step 4: Verify the configuration

1. DNS propagation: It may take some time (typically up to 48 hours) for DNS changes to propagate throughout the Internet. You can check the status of your DNS configuration using tools like dig or nslookup.
2. Enable HTTPS: Once your domain is correctly pointing to GitHub Pages and the changes have propagated, GitHub can automatically create an SSL certificate for HTTPS. Go back to the "Pages" settings in your GitHub repository to ensure HTTPS is enabled. It might take a short while for the certificate to be ready after the DNS changes.

Step 5: Update your site content

If you've linked any resources or internal links using your previous GitHub Pages URL, you may need to update these to reflect the new custom domain. This ensures that your site navigation remains intact and SEO is not adversely affected.

Troubleshooting

• If you encounter issues, verify that the DNS records are correctly set as per GitHub's requirements.
• Check the repository settings to confirm that the custom domain is correctly listed in the CNAME file.
• Review the GitHub Pages documentation or the GitHub community forums for specific troubleshooting steps if you encounter persistent problems.

GitHub Pages private repo

While GitHub Pages is generally used for public visibility, you can also use it with private repositories. However, the visibility of your GitHub Pages site from a private repository depends on your GitHub plan:

• GitHub Free for user accounts: You cannot host a private repository's website unless the repository is public.
• GitHub Pro, Team, or Enterprise accounts: You can host websites from private repositories, and the site will be publicly accessible even though the repository is private.

How to deploy GitHub Pages

Deploying GitHub Pages is straightforward. After enabling GitHub Pages in your repository settings and setting the branch and directory, each commit pushed to the specified branch will automatically trigger a deployment. GitHub does the heavy lifting by building the site from the static files you push.

GitHub Pages 404 errors

A common issue with GitHub Pages is encountering a 404 error, which can occur for several reasons:

• File paths: Ensure all links and references are correct. GitHub Pages is case-sensitive, unlike some local development environments.

• Custom domain configuration: If you recently added a custom domain, ensure your DNS settings are correctly configured and propagated, which can take up to 48 hours.

• SPA routing: If you're using a single-page application (SPA) framework like React or Angular, you'll need to configure your site to redirect all requests to your index.html. You can do this by adding a 404.html file with a script to redirect to index.html, ensuring that the SPA router takes over.

For further reading on GitHub Pages, see the official GitHub documentation.