Yesterday, I migrated my blog to Hugo.

GitHub Pages

While the migration was straight forward, I was a bit puzzled with the deployment process to GitHub.

For those who don’t know yet, GitHub enables all users to have an own website, called GitHub Pages, with a URL like https://your-user-name.github.io.

Previously I used Lektor. The source code for my site lived in https://github.com/jugmac00/jugmac00.github.io.source, and was deployed by Lektor to https://github.com/jugmac00/jugmac00.github.io.

Easy enough.

Time for confusion

For Hugo, this was not that straight forward. Some deployment tutorials mentioned a public dir in the same repository, others a gh-pages branch, the official documentation just shows an GitHub action with zero explanation, but actually no tutorial (that I found) mentioned explicitly you have to push all your templates into https://github.com/jugmac00/jugmac00.github.io. Possibly this is too obvious for the rest of the world, but it was not for me :-)

As my repository already contained the rendered HTML, still from Lektor, I did not want to start experiments.

I re-read the GitHub pages help, and finally went into the settings of the GitHub repository.

When you click on “Pages”, you can choose where from your GitHub Pages should be rendered, e.g. from a directory or another branch.

Now it made click!

When I had another look at Hugo’s GitHub Pages deployment action, I figured out, I need to create a new branch e.g. called main, in my existing repository, but without any commits from Lektor. How?

Empty branch

Turns out the git checkout subcommand has an --orphan option.

git checkout --orphan main

This creates a new branch, with zero commits!

I then deleted all files generated by Lektor, moved my new Hugo source in there, added the GitHub Action from above mentioned documentation, git committed and pushed, and crossed fingers.

And it worked out.

The action deployed to a new gh-pages branch, which I then had to choose from the repository’s setting.

Conclusion

While working with Hugo is a breeze, the deployment process was super confusing.

I created an issue on Hugo’s GitHub project. I wonder what the reaction will be.