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!
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
Once Hugo is installed we can test the installation by running
hugo help in the command prompt or
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
$ hugo new site your-sitename-here
This will create a scaffolding for your site you can view it in your finder
or in your terminal via the
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/productsfor 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:
$ hugo new post/first-post.md
Now edit the file in content/post/first-post.md, it will contain something similar to the following by default:
+++ date = "2016-09-26T13:19:03+07:00" title = "first post" +++
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
+++ date = "2016-09-26T13:19:03+07:00" title = "first post" +++ Hello world!
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
$ hugo server
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:
$ git clone --recursive https://github.com/spf13/hugoThemes.git themes Cloning into 'themes'... remote: Counting objects: 880, done. remote: Compressing objects: 100% (5/5), done. remote: Total 880 (delta 1), reused 0 (delta 0), pack-reused 875 Receiving objects: 100% (880/880), 669.20 KiB | 288.00 KiB/s, done. Resolving deltas: 100% (506/506), done. Checking connectivity... done.
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…
To use a theme just start Hugo with the
--theme parameter like so
$ hugo -t ThemeName
Or you can add to your
The ThemeName must match the name of the directory inside
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
cactus have a look around there are so many to choose from!
So you have now generated a website with a hello world post, what else can we do?
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
+++ tags = ["welding", "metal work"] categories = ["posts"] +++
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
$ hugo new post/tig-welding-a-bike-frame.md
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..
$ hugo new post/welding-a-roll-cage.md
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]
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
$ hugo-gallery static/images/welding-photos welding "Photos of my insane welding skills"
localhost:1313/welding to view the content.
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.
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!