Skip to content

Instantly share code, notes, and snippets.

@karldreher
Last active April 10, 2024 02:58
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save karldreher/a91d668f8c8f1d5d9dcc7d1a45a6f229 to your computer and use it in GitHub Desktop.
Save karldreher/a91d668f8c8f1d5d9dcc7d1a45a6f229 to your computer and use it in GitHub Desktop.
Just Enough Hugo

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 of hugo. 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.

Bonus Points

Read about a project a passionate Hugo user created to lint frontmatter.

https://github.com/karldreher/fmlint

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment