Adding a netlify.toml to a Hugo Site

About a year has passed since I moved to a Hugo + Netlify environment, and because nothing in particular had gone wrong I had left it alone, but I finally got around to setting up netlify.toml.

The theme used on this site: Beautifulhugo (submodule)

netlify.toml

The official page has the format for netlify.toml, so create it under hugo with the following content

[build]
publish = "public"
command = "hugo --gc --minify"

[context.production.environment]
HUGO_VERSION = "0.74.3"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

[context.split1]
command = "hugo --gc --minify --enableGitInfo"

[context.split1.environment]
HUGO_VERSION = "0.74.3"
HUGO_ENV = "production"

[context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
HUGO_VERSION = "0.74.3"

[context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

[context.branch-deploy.environment]
HUGO_VERSION = "0.74.3"

[context.next.environment]
HUGO_ENABLEGITINFO = "true"

• When the theme is a submodule

You need to specify the theme in the build command, so add --theme=beautifulhugo

[build]
publish = "public"
command = "hugo --theme=beautifulhugo --gc --minify"
....

• Checking the Hugo version

Also, make the HUGO_VERSION inside netlify.toml match the version you are using locally

$ hugo version
Hugo Static Site Generator v0.74.3/extended darwin/amd64 BuildDate: unknown

• git push

Once you have finished creating and editing netlify.toml, git push

$ git add .
$ git commit -m "add netlify.toml"
$ git push

Note that even if you specify the build command in the Netlify admin screen, netlify.toml takes precedence.

Once the git push finishes without trouble and the automatic deploy on Netlify completes, you can confirm it in a log like the one below.

The log after creating netlify.toml

....
10:23:37 AM: Installing Hugo 0.74.3
....
10:23:41 AM: ┌────────────────────────────────────┐
10:23:41 AM: │ 1. build.command from netlify.toml │
10:23:41 AM: └────────────────────────────────────┘
10:23:41 AM: ​
10:23:41 AM: $ hugo --theme=beautifulhugo --gc --minify
....

I could confirm that the build ran in an environment with the Hugo version (0.74.3) and the theme option (–theme=beautifulhugo) specified in netlify.toml.

If you do not create netlify.toml, the build uses Netlify’s default values, so the Hugo version stays at 0.54 forever.

Note also that even if you set the Hugo version in netlify.toml to the latest one, the theme may not support it, so setting it to the latest is not necessarily the right choice.
If the build fails, it may be a good idea to work your way down through the versions.