Host a Hugo Theme Example Site

So you've written yourself a flash new theme for your Hugo based website. Perhaps you even want to share it on the Official Theme Collection, but what's a simple way of creating a demo site for people to try out, and preferably for free? Luckily it's not too hard, but also not completely obvious.

There are a quite a few options for hosting of a Hugo static site, but for this example we'll use Render, even though it'll probably work in a similar way for other providers.

The first thing you need is a Hugo Theme with an included site in the exampleSite folder hosted on a publicly accessible repository like Github, Gitlab or Bitbucket. We can use this Grey Book theme as an example.

Normally to host a Hugo site stored in a repository, you just provide the repository link, and then Render clones the repository into a directory /opt/render/project, then launches the build command hugo --gc --minify on in that directory.

Usually the site within exampleSite will include and entry like the following in the config.toml file:

theme = theme-name"
themesDir = "../../"

Which means, instead of looking in the usual Hugo site root directory of themes for a folder that matches theme-name, it should instead look one level above the site root directory, e.g. so that it finds the theme's own directory, from within.

If you run hugo server within a theme directory's exampleSite on your local computer, this works without an issue, but…as we saw above Render clones it into a folder called /opt/render/project, so unless your theme is called 'project', the build command is going to complain about not being able to find the theme module.

The One Simple Trick^TM is that you can run other commands within the build command on Render which allows you to change the folder directory structure so it works, specifically:

mkdir theme-name
mv * theme-name/.
hugo -s theme-name/exampleSite --gc --minify

This moves the content of what was cloned from the repository into a new folder named after your theme, and changes the hugo command to use the theme-name/exampleSite directory as its source directory (hence the -c option).

This does generate a warning, that you are trying to move the directory theme-name into itself, but mv is smart enough not to do that impossible task, and it all works. You can't add newlines into the build command, so you have to separate the above commands with a semi-colon, and it then all looks like:

mkdir theme-name; mv * theme-name/.; hugo -s theme-name/exampleSite --gc --minify

Which is a bit cramped, but has the same effect.

One last change is to tell Render where to find the compiled site. Since you've just moved the source contents into a new folder, and then are using a sub-folder of that, you need to update the 'Publish directory' to be theme-name/examplesite/public.

Then let it run through and enjoy your freely hosted demo site. Assuming you leave 'Auto deploy' enabled, this will also automatically update as you push changes into the theme's repository.