Making classy web sites for free using Hugo

/

A while back I read a great post from David Parker about using the Hugo program to produce static web sites that you can host on GitHub. I’ve had a go with this, using the amazing meghna template. You can find the result here.

It’s been a great learning experience. Things I’ve learned:

  • The Hugo program will serve out a test version of your web site pages which you can view on your local machine. Each time you update a local file, the test web site updates automatically. This is a great way to preview your site, but beware of browser caching which can cause changes not to propagate. I lost a lot of time wondering why some changes hadn’t worked when they had.

  • if you want to map your Hugo site to a domain the source repository must be unique for a particular GitHub user or organisation and have the “.github.io” string on the end of its name. You can host web sites from other repositories in your GitHub account, but these will always have urls which are on the GitHub site.

  • David’s howto does a cunning GitHub worktree thing to allow both the web site source and the served pages to be on two different branches of the repository. He presents a batch file that will update the web site on the Master branch of the repository (the one containing the site) but if you want to push changes in the source files to the source repository you will have to do this by hand. I got myself into a bit of a tizzy using the GitHub desktop client to manipulate the site files. I’d advise you to do everything from the command line.

  • A GitHub repository that is mapped to a domain name must contain a CNAME file which gives the name of the domain being used. If you use David’s vanilla batch file to update your site you’ll find that the CNAME file is not replicated. You can fix this by adding the CNAME file to your static folder on your site repository or by changing the batch file to create a new CNAME file each time after it has wiped the old site prior to making the new one.

  • If you are mapping a domain name to your site and you want to use HTTPS (and you should) the address that you put in the config.tohtml file must be the domain name, not the GitHub address

  • If you add the

    RelativeURLs=true

    CanonifyURLs=true

    lines to your config.tohtml file these will break some of the megha features, notably the scrolling background images

  • You may have to modify some of the html files in meghna to remove references to a local php server used for mailing that is not available on a GitHub site

If you want to make a classy web site on the cheap (actually free) then I strongly recommend that you take a look at Hugo and the lovely templates that there are available for it.