Start Building Sites With Hugo & Netlify

Photo: Unsplash

I am a big fan of Netlify. I use it to power this blog and to host some small project sites. It is free for single users, provides a simple static site deployment process and SSL for your sites. What is not to like?

I recently had a new site to set up and headed straight over to Netlify. In the past, I have tended to opt straight for Jekyll. This time I thought I would use Hugo instead. Hugo is a static site generator built using the Go programming language. What follows is a simple how to get Bitbucket, Hugo and Netlify up and running. (Note, Bitbucket can be swapped out for Github or Gitlab etc)

The first thing is to install Go via your package manager, Brew or on Windows from here. Then you need to install Hugo by following the instructions from here.

Now we want to use Hugo to create our static site. Switch to the directory you wish to create the site in and use:

$ hugo new site NAME_OF_STATIC_SITE

Obviously, replace NAME_OF_STATIC_SITE with the real name of your site.

Now, let’s switch into our new site and initialise a new git repository.

(To keep things simple I am going to make NAME_OF_STATIC_SITE MySite)

$ cd MySite
$ git init

I then copied into the MySite directory my README.md and a .gitignore file specific for Hugo that I found here. Now we have added the supporting repository files we can hook up Bitbucket:

$ git add --all
$ git commit -m "Initial Commit For MySite" 
$ git remote add origin https://url_to_mysite_repo
$ git push -u origin master 

Again, change the origin URL to match the one provided by your Repository.

The next thing is to apply a Hugo theme and to configure MySite.

To start, find the theme you want to use as a starting point for MySite on Hugo Themes. Next, you can follow the download link next to the theme to install it. You can add the theme as a git submodule which will allow you to get the latest changes and fixes from upstream. This is up to you. Most people I have spoken to use a theme as a starting point. If you want to then execute the following:

$ git submodule add https://url_to_theme_repo themes/THEME_NAME 

Either way you install the theme you will end up with a new directory in your MySite/themes directory. Most themes will outline how to use the theme’s example site files. This allows you to copy some styling and possible content and JavaScript files to the matching directories in your MySite directory. Make sure to ensure that your root config.toml file contains a line specifying the theme you are using:

theme = "downloaded theme name"

At this point you can navigate to the root of MySite and execute the following to test your site:

$ hugo server -D

This will result in some output such as

Building sites …
                   | FR | EN
+------------------+----+----+
  Pages            | 36 | 36
  Paginator pages  |  0 |  0
  Non-page files   |  0 |  0
  Static files     | 69 | 69
  Processed images |  0 |  0
  Aliases          | 14 | 14
  Sitemaps         |  2 |  1
  Cleaned          |  0 |  0

Total in 165 ms
Watching for changes in D:\Repositories\MySite\{content,data,i18n,layouts,static,themes}
Watching for config changes in D:\Repositories\MySite\config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/project-test/ (bind address 127.0.0.1)

One of the great things with Hugo is that changes you make to your source code are hot loaded into the browser. You can test this by modifying one of the values in your layouts and see it appear immediately on the screen.

Once you have finished modifying the theme and configuring your site then you need to publish it. You should ensure all your changes are committed to git and pushed to your origin repository before continuing.

Let’s get Netlify running now. Login to Netlify and from the Sites page click “New site from Git”. It will ask you to select your git provider and authenticate your access. Next, it will ask you to select the repository with your site in. Select the repository and then enter the build command and publish directory details. For a simple site like we are building then hugo for the build command is fine. If it needs certain options passing we can come back and adjust this later anyway. The Publish directory should be public.

Under the Advanced build settings, you need to create an environment variable called HUGO_VERSION. This should be set to the same version of Hugo you are running locally. You can get that information by running:

$ hugo version

Enter the version into the environment variable value field and click “Deploy Site”.

You can then go to the Sites page in Netlify and see your new site has been created. It will have already started to deploy the site. While on the Sites page I generally rename the site name away from the random name they assign. I then click the Trigger Redeployment button to redeploy under the new name.

I then head to the Deploys page and ensure the site has been deployed correctly. If it has failed then you can click on the deployment log for a full overview of what has gone wrong. At least to get enough information to correct the issue or Google it!

You should now have a fully working site ready for you to start to build out and configure. Remember every time you push your changes to origin the site will deploy. Netlify has ways of previewing changes and handling different branching strategies. I will look at them more in an upcoming post.

If you have comments or views on developing sites with Hugo then contact me via twitter or email.