www 101

All you need to know about the internet

Have a Question?

If you have any question you can ask below or enter what you are looking for!

Make Creating Websites Fun Again With Hugo

Final product image
What You’ll Be Creating

Static sites are popular for many reasons – avoiding overkill solutions and keeping a project simple without databases, dependencies or specific server side configurations (no PHP, no MySQL/MSSQL, .NET, Python, Ruby, and so on) makes it very simple to deploy and be robust against numerous possible vulnerabilities; as ultimately it is just HTML pages being served to the user.

In this guide i will show you how to setup your development environment with Hugo and build your first static Hugo website.

A Brand New Approach to Static Websites

The legendary design acronym KISS – Keep It Simple, Stupid can be well applied here to Hugo and how it approaches the static website generator space. 

Built in Go, Hugo is rapidly fast to compile your static pages (it takes fractions of milliseconds to compile a small site – and can do thousands of pages in seconds) 

Also Hugo provides essential tooling to the static website workflow (including deployment and migration tools), allowing developers and designers to focus on the fun parts – building websites and being creative. Without needing to get caught up in any of those setup / dependency issues / architecture topology considerations.

Why Static Websites?

Ultimately when we build content based websites we can assume some generalities across all sites and Hugo gives a framework for that; where we can take content types be it posts, categories, reviews or products and organise the data, give them a specific look via template and apply stylesheets – going forward we can then really drive it anywhere we need within the HTML/CSS/JS static website space – and when you think about it pragmatically – that is really a very large space allowing a huge amount of room for creativity.

jQuery will run fine and there is nothing stopping you using third-party (or your own) services on your static page if you need them. So don’t limit yourself by thinking you cannot integrate other repos/apps into your static sites. It’s really not the case and you can use any of the JS out there!

So for a few pages of a company brochure type website, with a link to a google forms for contact us (hugo cannot do form processing yet) or a email link it will be ideal, and if you need some data displaying also from a feed you can use javascript to handle that part. 

How Can It Work for My Business/Clients?

Taking for example a small store / boutique or freelancer, with a few products or services that does not require an entire ecommerce solution yet – just some product information and a contact us link. Hugo can do it in a morning. And finding hosting is going to be next to nothing – it’s just static html after all.

So really for sole business owners who could be working in or outside the tech space that just require simple business card type sites – on low to nothing budgets, or even on a slightly larger scale it can work fine for project documentation on GNU projects for example or even at a stretch for start ups or SMEs who just need a presence for right now today – this is where Hugo can be utilised fully to create a high quality website.

What Are the Limitations of Static Sites?

What Hugo cannot do is dynamic content, e.g database driven forms, searching or user systems… and if that is what your looking for then Hugo certainly is not what you want. But for the other times, when you find yourself saying – can’t we just put up a basic page for this? Static website generators are the best place to go in my opinion. Also be aware that Hugo is not the only static site generator. There are many out there and have been around for a long time, here’s a top list of them here

For building live content blogs such as news sites covering events that are currently developing, Hugo could be a great solution to quickly knock up a page for that coverage to be linked from your main site, getting it online in minutes and meaning you can continue to add to it fast and redeploy the changes very quickly.  But for making a whole news site with search and many writers, it would be really not suitable to use Hugo.

Where Hugo also lacks is in using more advanced tools for its asset pipeline such as EcmaScript6 and SASS – if you want that you will need to include Gulp or Grunt to get the job done, otherwise just straight up CSS and JS is what we will be working with.

Also contact us forms and search can be achieved but only by using 3rd party methods (e.g Google) to achieve this. Alternatively though nothing is stopping you embedding your own solution from your own service at that point.

Your Home Development Environment

Hugo is written in Go and has support for many platforms, to view all the releases you can go here 

For macOS users with HomeBrew, installation can be done as follows:

brew update && brew install hugo

More information on installation for Mac OSX and Windows

Once Hugo is installed we can test the installation by running hugo help in the command prompt or hugo version 

Making Your First Static Website With Hugo

Now we have hugo installed we can start creating the website. Run the following command replacing ‘your-sitename-here’ with your project name

This will create a scaffolding for your site you can view it in your finder

Hugos default files

or in your terminal via the tree command

Viewing the hugo files with tree in the terminal

Hugo has created 5 sub-directories and 1 file, which it uses to create the final website from here’s what they all mean:

  • archetypes: here we define what our content is, we can set default tags or categories and define types such as a post, tutorial or product here
  • config.toml: main configuration is in here, we can define all of the websites title, language, urls etc here
  • content: the content pages of the site are stored here, sub directories are used for sections to help organise the content, create a content/products for your products content for example
  • data: Site data such a localisation configurations go here
  • layouts: layouts for the Go html/template library which Hugo utilises go here
  • static: Any static files here will be compiled into the final website, total freedom is allowed so you can serve any css,js or image file for example.
  • themes: Create new themes or clone themes from github into this directory to use them with your site. 

“Hello World” in Hugo

We need to add a post to see the site we just created, do so by using the following command:

Now edit the file in content/post/first-post.md, it will contain something similar to the following by default:

Front Matter

The content inside +++ is the TOML configuration for the post. This configuration is called front matter. It enables you to define post configuration along with its content. By default, each post will have the configuration properties shown above.

Add some text after the +++like so:

Serving Data and Live Reload

So we can see the live reload functionality that is inbuilt with Hugo, let’s make some changes to the site and see what happens. 

First start the server by running

Now if you make some changes to your file, you will see Hugo instantly reload.

Your website will be available at http://localhost:1313 but hold on – you will still only see a blank white page at this point, because we have not defined a theme!

Add a Theme

Hugo has a very robust and versatile theme library as it uses Go’s html/template library. Themes are easy to work with, installation is done by simply cloning the repository of a theme into the themes directory for your Hugo site. 

Hugo does not come with a default theme, so you must set one.

There are loads of open source themes to choose from that you can look at here https://themes.gohugo.io/  

Let’s add loads of themes to our site so we can have a play with all of them and see what we like. Do so by running the following in our hugo directory:

You will now see a whole heap of themes being cloned into your site. There are a lot so you will have time for a break while it clones…

A bare amount of themes are  available for Hugo

Using a Theme

To use a theme just start Hugo with the -t or --theme parameter like so

Or you can add to your config.toml :

The ThemeName must match the name of the directory inside /themes.

When you have chosen a theme name from the directory, start you server with hugo server --theme=ThemeName and take a look on http://localhost:1313  

Here are some examples from some of those themes we cloned, I used begcrisp andcactus have a look around there are so many to choose from!

The beg theme on your mobile device screen will work great
An example of the crisp theme from Hugos theme repository
An example of testing out a theme in Hugo with your first post

So you have now generated a website with a hello world post, what else can we do?

Building a Blog

Making a basic blog is really easy and feasible to do even in a day with Hugo. First you will need to define a archetype for the default post, so create a new file in archetypes/default.mdand add the following as front matter

Here we set some default tags, for a blog on welding we can be sure we want these tags on all our posts, and we make a category called posts just so we have a default when we create a post.

Now add your first post via the terminal like so 

This will create a post with the archetype you defined before, you can now open it in a text editor and start writing away in markdown format!

Let’s add some more posts..

Again to add content, just open the file Hugo created and start adding content to the end of the file after the front matter.

Building a Photo Gallery

To build a photo gallery with Hugo we will use the excellent tool hugo-gallery available on GitHub

It’s usage is as so:

hugo-gallery <Source Path> <Destination Section> <Title> [BaseUrl]

The hugo-gallery tool will create a new posts directory containing a markdown file for each image in source directory allowing for an ordered slide show. It will read all of the files out of the Source Pathdirectory and save them in the static directory of the hugo site. 

It will create a new directory inside of the content directory based on the Title provided e.g content/welding

For example: 

Visit localhost:1313/welding to view the content.

Deployment

Hugo has several tools for deployment such as hugomac which is a OSX menubar app enabling the user to easily publish to EC2 hosting. No command line needed.

Also hugodeploy provides a SFTP setup to deploy with, or you could just use the Automated deployments Hugo comes with. 

Conclusion

Static site generators have been around for a while, and Hugo really builds on the tool set making it fast and easy to knock up sites, or even migrate an existing site from wordpress to hugo. There are a lot of tools for Hugo, including front-end editors check them out here https://gohugo.io/tools/

Going forward it would be good to see more modules for Hugo giving support for things like a contact form and gallery support, or related posts for example. 

The Hugo roadmap does have a lot of exiting ideas like dynamic image resizing, support for rsync and image import from hosting providers and easier hosting with AWS EC2 and github integration.. so if you are not using Hugo yet be sure to check back on the project as it develops!