Hugo101 — Getting started with Hugo and deploying to Netlify.
Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again. It builds pages when you create or update your content. Websites built with Hugo are extremely fast and secure like https://bolajiayodeji.com. In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
Hugo sites can be hosted anywhere, including Netlify, Heroku, GoDaddy, DreamHost, GitHub Pages, GitLab Pages, Surge, Aerobatic, Firebase, Google Cloud Storage, Amazon S3, Rackspace, Azure, and CloudFront and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
In this tutorial, I’d show you how to build your first Hugo site and deploy to Netlify. Let’s roll :)
PS: This article was first published on my blog here
- Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. Watch a video here to see how fast Hugo is
- Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins.
- We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
- Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code and you’re done.
- Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites.
- Hugo allows you to output your content in multiple formats, including JSON or AMP and makes it easy to create your own.
All features can be found here
For this tutorial, we’re going to build a Simple Blog with Hugo.
PS: I would be using a windows machine in this tutorial, so all steps would be based on windows, but I added installation guides for other operating systems.
I’ve also created a repository with starter files which can be found here. Use the installation guide to get Hugo running on your machine and fork the starter files. Ensure you follow the steps.
- Code Explorer
- Install Hugo
- Fork the starter repository here
- Create a new site
- Deploy to Netlify
To start using Hugo, you need to first install it.
Hugo was written in Go, but you don’t need to install Go to enjoy Hugo. You only need a precompiled binary!
Hugo currently provides pre-built binaries for the following:
- macOS (Darwin) for x64, i386, and ARM architectures
Installing on Mac
Follow the video below to install Hugo on your macOS or read the Installation guide. There are several techniques for installing Hugo on mac, so I won’t be going through them. BTW, I’m using a windows machine so I possibly don't know how to guide you :)
Installing on Windows
Follow the video below to install Hugo on your windows machine or read the Installation guide. This video is a complete guide, but if you have installation issues, please let me know in comments.
Installing on Linux
To install the “extended” Sass/SCSS:
snap install hugo --channel=extended
To install the non-extended version without Sass/SCSS support:
snap install hugo
- Using the Debian Package for Ubuntu.
This installs the “extended” Sass/SCSS version.
sudo apt-get install hugo
- For Arch Linux
sudo pacman -Syu hugo
- For Fedora, Red Hat and CentOS
sudo dnf install hugo
Installing on OpenBSD
doas pkg_add hugo
Creating a new site
You can simply fork the starter repository. It contains the finished work with Theme and custom posts. Creating a site with Hugo is quite simple, just follow the following steps.
- Create a new site with name
hugo new site Hugo101
Now you should have a new folder
Hugo101 with subfolders:
Full directory structure explanation can be found here
- Add a new theme. All Hugo themes can be found here. For this tutorial, we’d be using the Hugo Base16 theme by Hylke Visser.
This video would show you how to install and use themes on Hugo. Installing is very simple, you just need to find the theme you like and download it into the
themes subdirectory. If you’re using the starter file, I’ve done that already.
- After installing the theme or cloning the starter file, start the Hugo server
hugo server -D
Now your new site should be available at localhost:1313.
- To add a new post
hugo new post/my-first-post.md
This would be added in
- Some posts parameters would be added at the top of the file. I’ve added some additional parameters you might need.
title: "my first post"
tags: ["markdown", "GitHub", "website"]
categories: ["hugo", "base16"]
- To build files, run
Now your directory would have a new subfolder
public , this is the final build. Hugo takes a source directory of files and templates and uses these as input to create a complete website. The
public is the complete website and is what you’d deploy.
- Configure Hugo for deployment
We would deploy to Netlify in the next section of this tutorial, but before that, we need to configure Hugo for Netlify.
Create a new file in the root of your project, If you’re using the starter file, I’ve added this already.
Paste this in it: (This is just configuring how Hugo should work with Netlify)
publish = "public"
command = "hugo --gc --minify"[context.production.environment]
HUGO_VERSION = "0.54.0"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"[context.split1]
command = "hugo --gc --minify --enableGitInfo"[context.split1.environment]
HUGO_VERSION = "0.54.0"
HUGO_ENV = "production"[context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"[context.deploy-preview.environment]
HUGO_VERSION = "0.54.0"[context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"[context.branch-deploy.environment]
HUGO_VERSION = "0.54.0"[context.next.environment]
HUGO_ENABLEGITINFO = "true"
Deploying to Netlify
Netlify is an all-in-one workflow that combines global deployment, continuous integration, automatic HTTPS and many other features.
Ensure you have a forked version of the starter files or a version of your own project hosted on GitHub
Create a Netlify account
Visit app.netlify.com and select your preferred signup method.
Create a New Site with Continuous Deployment
Select the “New site from git.” button
Select your git provider
Select the repository you want to use for continuous deployment.
For this tutorial, I assume its
Hugo101, else you can filter through your repositories in real time.
Here you select the branch you wanted published, your build command, and your publish (i.e. deploy) directory. The publish directory is
public. The following steps assume you are publishing from the
Build and Deploy Site
In the Netlify console, select “Deploy site” and wait for it to build
Once the build is finished, you should now see a “Hero Card” at the top of your screen letting you know the deployment is successful. You’ll see that the URL is automatically generated by Netlify. You can update the URL in “Settings.” Visit the live site.
Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site. You can add your own changes to the starter files and tweak as you wish.
Hugo is the world’s fastest framework for building websites. It is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. (Hugo docs)
Hugo is open-source and completely free, you can contribute to Hugo here
This is just a beginners guide, there’s still more to Hugo, head out and read the Hugo docs to learn more. Below is a list of useful resources you might need.
- Create a Hugo Theme
- Hugo Theme Components
- Introduction to Hugo Templating
- Content Organization
- Using a Custom Domain with Netlify
- Hugo configuration
- Hugo CLI commands
- Hugo variables and Params
- Hugo Pipes
- How Netlify handles Hugo versions