Deploy your theme to Netlify

tips & tricks
1

Netlify CI

After playing around with this for a bit, I finally got it to work.

To give you an idea, my usual workflow when updating my theme is something like:

  1. Make changes
  2. Commit and push
  3. Pull changes into my personal site, which uses the theme
  4. Test to make sure I didn’t break anything
  5. Commit pulled-in theme changes
  6. Rinse and repeat

Since my theme (and many others out there) use an example site, I figured all the ingredients were there to build the site. And it would be nice to see a live demo with my immediate changes.

So why Netlify, and not some other CI? Well, Netlify is free, fast, and easy. Enough said in my book.

All you need to make this work is (1) connect your GitHub account to Netlify, and (2) add a netlify.toml file at the root of your theme repo. Here’s mine. And here’s an example:

[build]
publish = "exampleSite/public"
command = """hugo \
  --source exampleSite \
  --config exampleSite/config.toml \
  --themesDir ../.. \
  --theme repo \
  --baseURL https://some-netlify-url.com"""

[build.environment]
HUGO_VERSION = "0.51"

Some notes:

  • Instead of the usual public folder for a regular site, you use the one from your example site
  • When Netlify clones your git repo, it does this from the folder /opt/build, then renames the git repo to repo
  • Make sure you don’t have the theme line set in your exampleSite/config.toml, because it will conflict with the --theme option you pass in

And there you have it. Here’s the live demo.

Local

If you just wanted to build your example site against your theme locally, navigate to the root of your theme folder, then run:

hugo server \
--source exampleSite \
--config exampleSite/config.toml \
--themesDir ../.. \
--theme <your-theme-repo-name>
6 Likes
2

I do it a slightly different way so that local builds work too, and theme components also work.

  • I don’t touch any of the Hugo CLI configs; I simply cd to the right dir and run hugo. Here’s my netlify.toml.
  • I then create a symlink to the theme in the exampleSite’s themes/ dir (similar to what you are doing with themesDir and theme). I create exampleSite/themes, cd to that dir and do ln -s ../.. my-theme-name, and I set theme = "my-theme-name" in exampleSite/config.toml.

With this in place, the same cd exampleSite && hugo works for local builds too.

Make sure you don’t have the theme line set in your exampleSite/config.toml , because it will conflict with the --theme option you pass in

Yeah, there is something funky about setting theme in config vs the -t CLI option… I have this unrelated hugo bug open around this topic.

3 Likes
3

This is wonderful, exactly what I was looking for. I’ve been maintaining 2 repos. One for the theme which includes the exampleSite and another for the live demo which contains a hugo root with the theme inside it.

It became annoying to deploy, and as I was copying the files from the live demo repo over into the theme repo I kept missing files.

I used the approach recommended by @zwbetz and it works great.

I can confirm even if you use --theme in the build command, if you have a theme key in your exampleSite/config.toml the Netlify deploy will fail.

You can see my repo here https://github.com/JugglerX/hugo-hero-theme

You can also run hugo server --theme hugo-hero-theme from the exampleSite folder on your local if that feels more intuitive.

4

@JugglerX Am happy to hear it was helpful.

On my 2nd theme, I use a setup more similar to @kaushalmodi’s.

[build]
  publish = "exampleSite/public"
  command = "cd exampleSite && hugo --gc --themesDir ../.. -t repo --baseURL https://vanilla-bootstrap-hugo-theme.netlify.com/"

[build.environment]
  HUGO_VERSION = "0.53"
5

Thanks to this post by @anthonyfok, I can now override the theme specified in the config file by setting the environment variable HUGO_THEME in netlify.toml

[build]
  publish = "exampleSite/public"
  command = "cd exampleSite && hugo --gc --themesDir ../.."

[build.environment]
  HUGO_VERSION = "0.53"
  HUGO_THEME = "repo"
  HUGO_BASEURL = "https://vanilla-bootstrap-hugo-theme.netlify.com/"

Edit: use HUGO_BASEURL env var per tip from @kaushalmodi

2 Likes
6

I can now override the theme specified in the config file by setting the environment variable HUGO_THEME

Most (if not all) Hugo config variables behave that way. Simply upcase a Hugo config and prefix with “HUGO_”, and you’ve got a valid env variable that you can use in lieu of that config variable.

So baseURL becomes HUGO_BASEURL, and so on.

1 Like
7

Nice. That’s good to know.

8

Just wondering if the significance and usage of this feature are adequately captured in the following:

https://gohugo.io/getting-started/configuration/#configure-with-environment-variables

and

https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml

If so Great!!