Hosting a Hugo or Next.js site on GitHub Pages is a straightforward process. In this article, we’ll walk you through the steps to host your Hugo or Next.js site on GitHub Pages.
Prerequisites
Before we begin, make sure you have the following:
- A Hugo or Next.js site set up locally.
- Git installed on your machine.
- A GitHub account.
Hosting a Hugo Site on GitHub Pages
Step 1: Generate the Static Site
If you’re using Hugo, generate the static site by running the following command in your Hugo project directory:
hugo
This command will generate the static HTML files and assets in the public directory of your Hugo project.
Step 2: Create a New Repository
Go to GitHub and create a new repository for your site. Make sure to give it an appropriate name and set it to public or private as per your preference.
Step 3: Initialize Git in your Hugo Project
In your Hugo project directory, initialize Git by running the following commands:
git init
git add .
git commit -m "Initial commit"
Step 4: Add the Remote Repository
Add the remote repository URL to your Hugo project by running the following command:
git remote add origin <repository_url>
Replace <repository_url> with the URL of the repository you created in Step 2.
Step 5: Push the Static Site to GitHub
Push the generated static site to GitHub by running the following command:
git push origin master
Step 6: Configure GitHub Pages
Go to your repository on GitHub and navigate to the “Settings” tab. Scroll down to the “GitHub Pages” section.
- Select the branch you want to use for hosting (e.g.,
master). - Choose the
/rootdirectory as the source for GitHub Pages.
Click “Save” to apply the changes. GitHub Pages will then build and host your Hugo site.
Hosting a Next.js Site on GitHub Pages
Step 1: Configure the Next.js Project
In your Next.js project, open the next.config.js file and add the following configuration:
module.exports = {
basePath: '/<repository_name>',
assetPrefix: `https://<username>.github.io`,
};
Replace <repository_name> with the name of your repository and <username> with your GitHub username.
Step 2: Create a New Repository
Go to GitHub and create a new repository for your site. Choose an appropriate name and set it to public or private.
Step 3: Initialize Git in your Next.js Project
In your Next.js project directory, initialize Git by running the following commands:
git init
git add .
git commit -m "Initial commit"
Step 4: Add the Remote Repository
Add the remote repository URL to your Next.js project by running the following command:
git remote add origin <repository_url>
Replace <repository_url> with the URL of the repository you created in Step 2.
Step 5: Push the Next.js Project to GitHub
Push the Next.js project to GitHub by running the following command:
git push origin master
Step 6: Configure GitHub Pages
Go to your repository on GitHub and navigate to the “Settings” tab. Scroll down to the “GitHub Pages” section.
- Select the branch you want to use for hosting (e.g.,
master). - Choose the
/rootdirectory as the source for GitHub Pages.
Click “Save” to apply the changes. GitHub Pages will then build and host your Next.js site.
Custom Domain Setup (Optional)
If you have a custom domain that you want to use for your Hugo or Next.js site hosted on GitHub Pages, you can follow these additional steps to set it up.
Step 1: Choose a Custom Domain
Decide on the custom domain you want to use for your site, such as www.yourdomain.com.
Step 2: Update DNS Records
Go to your domain registrar or DNS provider’s website and update the DNS records for your domain. Create a new CNAME record with the following settings:
- Host:
www(or any subdomain you prefer) - Value/Points to:
<username>.github.io.(with the trailing dot) - TTL: Default or your preferred value
Save the DNS record changes. This configuration ensures that requests to your custom domain are directed to your GitHub Pages site.
Step 3: Update GitHub Pages Settings
In your GitHub repository settings, scroll down to the “GitHub Pages” section and enter your custom domain (e.g., www.yourdomain.com) in the “Custom domain” field. Save the changes.
Step 4: Verify Custom Domain
After updating the DNS records and GitHub Pages settings, you need to verify the custom domain. GitHub provides a verification method that requires adding a CNAME file to your repository.
Create a new file named CNAME in the root directory of your repository and add your custom domain (e.g., www.yourdomain.com) as the content of the file. Commit and push the file to your GitHub repository.
Step 5: Enable HTTPS (Optional)
To enable HTTPS for your custom domain, you can use a service like Cloudflare or Let’s Encrypt. These services provide free SSL certificates and can be configured to work with GitHub Pages.
Follow the instructions provided by your chosen service to enable HTTPS for your custom domain.
Step 6: Wait for DNS Propagation
DNS changes can take some time to propagate worldwide. It may take several minutes to a few hours for your custom domain to start working with GitHub Pages. Be patient and periodically check your custom domain to see if it’s loading your site.
Once the DNS propagation is complete, your Hugo or Next.js site will be accessible through your custom domain.
Conclusion
Hosting a Hugo or Next.js site on GitHub Pages is a convenient and cost-effective option. By following the steps in this article, you can easily set up your site on GitHub Pages and even configure a custom domain for it. Enjoy publishing your Hugo or Next.js projects with the help of GitHub Pages!
