Summary
In this tutorial, we will learn how to host our statically generated website online using Github Pages. We will also be continuing from our demo project which we created in the Build A Website Using The Hugo Framework tutorial.
Prerequisites
Firstly, we need to create a remote Git repository to contain our project's code, therefore ensure you have registered a GitHub account. Also, to create the remote repository I will be using the GitHub command-line interface (CLI) which can optionally be installed using the commands below.
GitHub CLI Installation
When using macOS or Linux you can install the gh command using Homebrew with brew install gh.
If using Windows, you can install the GitHub CLI with the Chocolatey package manager using choco install gh.
For alternative methods see the GitHub CLI website for more details.
Remote Repository
Once registered to GitHub, create a remote repository using the online web interface or using the GitHub CLI steps below.
Using GitHub CLI
To create a repository we will use the command gh repo create REPOSITORY.
if this is the first time running the gh command, you will need to first link your GitHub account by using the command gh auth login and following the authentication steps.
Once authenticated navigate to your project's directory, as we are continuing from the Hugo Quick Start Guide this will be ~/demo/my-website/. If we create a remote repository from within the folder the gh repo create command should use the account associated with the Git project, however, if none is found you can specify the USER/REPO in the command.
gh repo create --public developercraft/demo-website
Building the Website
Once the website is online it will be available to view at the web address https://USERNAME.github.io/REPOSITORY, where USERNAME is your GitHub username and REPOSITORY the repository name you used, for example, https://developercraft.github.io/demo-website. Therefore let's update the config.toml file to use the new URL by replacing the baseURL entry to point to the new web address.
baseURL = "https://developercraft.github.io/demo-website/" languageCode = "en-us" title = "My New Hugo Site" theme = "fuji"
Now that the baseURL is correctly pointing to the new web address, we can build the source files to be published online. Typically we would use the hugo command which would output the content into the public folder, however, Github Pages require that the source files of the website should be located at the root repository or within the docs folder. Therefore, we will include the -d prefix in tandem with the hugo command to set the output directory to the docs folder.
hugo -d docs
Update Changes
There are changes to be committed, so let's add the changes with a message subject.
On branch main Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: config.toml Untracked files: (use "git add <file>..." to include in what will be committed) docs/ no changes added to commit (use "git add" and/or "git commit -a")
git add .
git commit -am "Added 1st post & build folder"
To simplify pushing changes to the remote branch we need to set the upstream to point to the remote main branch. Thereafter, git push should suffice for any future uploads.
git push -u origin main
Configuring GitHub Pages
Lastly, we will need to configure Github Pages to use the source files of the website. To do this head over to the repository using your web browser and in the repository settings, under Pages, change the branch from None to main and also change the publishing source directory from /(root) to /docs. Save the changes and the configuration should be complete.
Once GitHub recognises the changes (which could take a minute or so), the website should now be available at the baseURL address previously provided within the config.toml file – for example https://developercraft.github.io/demo-website
Conclusion
In this tutorial, we've learnt how to use the GitHub CLI to create a remote repository, how to build the website using Hugo, and how to configure GitHub Pages to serve the website online. Congratulations! You now have your website hosted online for the world to view! 🎉 🥳
What's Next?
Now that you have a website online, take it to the next level and have a custom domain name to further personalise your site!