Just Enough Hugo ๐
Follow the quickstart. Can’t get more straightforward than that.
Do not follow the advice regarding submodules. Submodules are horrible and you should not even think about them. We will discuss that point again later.
Stop before you get there, even if you don’t have a working site yet.
Themes ๐
As indicated by quickstart, you need a theme.
https://themes.gohugo.io/ is a good place to look, as is github. (many of these will point you to the github repo for the theme anyway).
Sites will indicate to you to do one of two different things; either submodule the theme or clone it to your repo. Both are terrible choices and there is one that’s not discussed upfront.
Hugo Modules ๐
Newer versions of Hugo do what could only be done with Golang before. There is better documentation for this now.
https://gohugo.io/hugo-modules/use-modules/
When you’re ready for a theme, follow the instructions above. Once you do it this way, you never go back. This is a much more lightweight and malleable approach than Git submodules.
You could technically manage the module with golang directly. It’s probably equivalent at this point.
Config ๐
https://gohugo.io/getting-started/configuration/ Choose Toml,Yaml,or Json according to your preference.
A good early practice is to start separating config into default, dev, and production configs. You only need to add specific values that you want to override in non-default configs.
config
โโโ _default
โ โโโ config.yaml
โโโ develop
โ โโโ config.yaml
โโโ main
โโโ config.yaml
You may also need to tie this in to CI in deployments, e.g. based on above:
hugo --environment $GIT_BRANCH
It should be pointed out this was written by someone more familiar with the config.
convention, which Hugo has apparently changed.
With v0.109.0 and earlier the basename of the site configuration file was
config
instead ofhugo
. You can use either, but should transition to the new naming convention when practical.
Development Loop ๐
Read about archetypes, set them up and add new content.
hugo new my-cool-archetype/something.md
Run hugo server
to see your stuff locally.
Deploying to Production ๐
Look into Vercel, Cloudflare, Netlify, Azure Static Sites or other hosting providers with built-in support.
Connect your repository to it directly. A common pattern is previewing from PR and deploying production from main
branch.
There’s no reason to roll-your-own with AWS or another static bucket website unless you’re really insistent to do that.