It has taken me a while to come to like Hugo. It is very fast but a lot of the documentation around how to do simple things is convoluted. I wanted to publish my Hugo site on Github Pages, just on the master branch. Most of the documentation I was finding involved 20 line bash scripts. I figured there had to be a more simple way so I sat down and learned some fundamentals.
Hugo Deployment Fundamentals
In the root config file (config.toml/yaml/etc) there is an option to specify where Hugo will publish content. By default it looks like this publishDir = "public" so whether or not it is written there, that is what is happening. So when you run the hugo command it will build all the static assets there.
This can be changes to publishDir = "docs" and if you run hugo the site will be built in a folder called docs instead of public.
Hugo Deployment
The documentation around publishing a Github project page is substantial. I am going to discuss publishing a site more generally which can be used as a github personal page. While obvious to some, it bears repeating that Hugo builds static websites and so wherever the build output is created that is what has to be deployed. To host your content on Google Cloud Storage or Github or any other static site hosting service the only files that are required are the ones that are built together in the publishDir. By default those are the files that are generated inside of the /public directory.
Go to Github and create an empty repo named after your username if you haven’t done so already.
Then to set up the project to deploy to Github run
cd path/to/hugo/site
hugo
cd public
git init
git remote add origin git@github.com:<your-username>/<your-username>.github.io.git
git add .
git commit -m "Deploying to Github!"
git push origin master
And you are done! Go to your Github pages site and check it out.
Debugging note
After deploying, if you go to your page and you see images and styling missing but it was working on your local hugo server there is a good chance that your baseurl is configured incorrectly.
Open up your root config file and change the baseurl to baseurl = "https://<your-useranme>.github.io/"
run the hugo command again, re-add, commit, and push the change. Refresh and you should have your styles now.