If you already have some experience with the command line, git, and a spare server, you can set up a static site like this one in less than two hours. Once finished, you’ll be able to update the site automatically with a simple git push. Read on to learn how!

A disclaimer: This is a method that has worked for me. I would do it better again, and should write another post about how to get this working with cloudflare pages which matches the current setup.

Additionally, some of the following instructions are not best practices, specifically leaving the binary in the repo and deleting the .git directory in the theme directory. These decisions are for reasons that work for me, particularly making it easier to deploy and work with in multiple environments with minimal configuration.

Getting Started

First, let’s make sure we know what we’re dealing with.

• Linux is the operating system that should be installed on your server, and will host Hugo and Caddy.. This tutorial has a debian-based distribution like Debian or Ubuntu in mind, but others like Arch should work just as well.
• Caddy is a modern (as of 2019) web server that will serve your static site. It is written in Go and includes fantastic features like automatically pulling from git, automatic HTTPS through letsencrypt, and tons of plugins.
• Hugo is a static site generator that allows you to quickly create sites with sections, taxonomies, and articles. This software will take a directory and use it to generate a static site. This directory will include the theme, content, configuration, and other optional features like archetypes.
• Git, as you should know, is a way to manage source control and is frequently used to store your code in a repository like github or gitlab. This is how you will manage the code of your site and sync your changes to the server without having to execute a command.

First, make sure you have the following:

• A spare Linux server accessible by ssh. OpenBSD and other operating systems will work, but instructions may differ from this tutorial. This should have a domain name for HTTPS and a pretty URL, but is not necessary. You don’t technically need a server, and can use any spare Linux system including your laptop or Windows Subsystem Linux to test this method
• A Linux command line environment which has git and an internet connection which you can develop your site on
• An account on github or gitlab and an understanding of git

Starting your Hugo Site

Installing Hugo

Firstly, get your project environment set up. In my case I made a folder at /home/username/code/newwebsite/, where newwebsite is the name of your project.

Then install Hugo. My recommendation is to download the latest version of a release that matches your platform. In my case this was hugo_0.54.0_Linux-64bit.tar.gz. Extract this with tar -xvf to this project directory (in my case /home/username/code/newwebsite/ and delete any files besides the hugo binary. Your newwebsite folder should be empty besides this binary.

Putting this binary in the root directory of your site is not standard practice and introduces some bloat to the repo. However I find this convenient as the repo has everything you need to develop, test, and deploy the site. You may put this binary elsewhere.

In this project directory, run ./hugo new site . --force. Let’s explain this command: ./hugo runs the binary in the current folder, new site . creates a new site at the current directory, and –force allows this site to be created in a folder that already contains something, in this case the hugo binary.

The directory should contain the following files.

archetypes/  config.toml  content/  data/  hugo  layouts/  static/  themes/

The only things required for a functional site are config.toml, content/, themes/, and the hugo binary unless it’s installed elsewhere. You could delete everything else if all the empty directories annoy you. More info on this directory structure in the official documentation.

Now you have a skeleton site up and running! If you run ./hugo server, it will start up a development server with an address listed in the output of this command, in my case http://localhost:1313/. It won’t show anything since you have no content and no theme, but you know it’s working.

Installing a Theme

Themes are installed by putting a theme in the newwebsite/theme directory, and then specifying in the configuration file the theme’s name.

For this we will use what I use for this website, hugo-bootstrap. In your project directory, clone this repostory into the themes directory: git clone https://github.com/Xzya/hugo-bootstrap themes/hugo-bootstrap.

Something I like to do is disable the git directory: mv themes/hugo-bootstrap/.git themes/hugo-bootstrap/.git-bak. You could keep this source control by using git submodules which I do on some of my sites, but this makes deploying the site a bit more difficult, and you’ll probably be editing the theme files anyways.

Now copy the example configuration for the theme into your project directory:

username@COMPUTER:~/code/newwebsite/$ cp themes/hugo-bootstrap/exampleSite/config.toml .

Now open a separate terminal window and run ./hugo server and you should see the theme, albiet without content. Keep this terminal running the server in the background – as you add content and change the theme, Hugo will notice you changed something and rebuilt the site automatically and refreshing the web page. This will make for very speedy development!

Understanding the config.toml file