How to Deploy Your Hugo Site to GitHub Pages: A Simple Step-by-Step Guide

Many guides online, including the Hugo documentation, tend to complicate the process of deploying a Hugo site to GitHub Pages. They often suggest creating multiple repositories or using submodules, which can be unnecessary. This guide aims to simplify the process, making it as straightforward as possible.

Prerequisites

Before you begin, ensure the following:

• You have a GitHub account.
• You have a text editor installed.
• You have a fully functioning local Hugo site. This means you can run your site locally by using hugo serve -D in your command prompt while in the Hugo site folder. This guide specifically covers hosting a local, working site on GitHub Pages.

Step 1: Creating the GitHub Repository

First, your local Hugo folder needs a place on GitHub.

1. Go to your GitHub profile page and navigate to Repositories > New.
2. Under Repository name, enter the exact name of your Hugo site folder and click Create Repository.
3. You’ll be directed to a page with an HTML link; copy this link.

Step 2: Preparing Your Hugo Folder

Next, we need to adjust your local Hugo folder for web deployment.

1. Open your Hugo site folder in your preferred text editor.
2. In the config.toml file, add the following line at the top:

   publishDir = "docs"
   

3. Find the line that says baseURL = "https://example.org" and replace the URL with:

   baseURL = "https://yourgithubname.github.io/yourgithubproject/"
   

   Make sure the URL follows this format exactly.
4. Save the file.

Step 3: Connecting Your Hugo Folder to the GitHub Repository

Now it’s time to push your files to the GitHub repository.

1. Open Command Prompt and navigate to your Hugo site folder.
2. Run hugo serve to generate the docs folder we configured earlier.
3. Initialize an empty Git repository by entering git init.
4. Add your GitHub repository as the remote origin with:

   git remote add origin <paste the link you copied from the "Creating the GitHub Repo" step>
   

5. Check the status of your files with git status—you should see uncommitted items in red.
6. Stage all your files with git add --all.
7. Commit the files with:

   git commit -m "initial commit"
   

8. Push your files to GitHub with:

   git push -u origin master
   

Step 4: Enabling GitHub Pages

Finally, let’s set up GitHub Pages to host your website.

1. In your GitHub repository, go to Settings.
2. Scroll down to GitHub Pages and under Source, select master branch /docs folder and click Save.
3. Refresh the page and scroll back down to GitHub Pages—you should see a link to your new website!

And that’s it! Your Hugo site is now live on GitHub Pages.