David Clinton
Outline
All the tutorials in this course:
- Understanding the Static Website Universe
- Building a Static Website on S3
- Optimizing Website Security and Performance
- Working With the Hugo Static Site Generator
Installing Hugo for whatever operating system you're using is simple. This page will show you everything you need to know. So I'm going to assume you've got that far on your own. In case you're curious, I'm going to be working on Ubuntu Linux - because that's all I've been working on for the past fifteen years or so. But besides for the simple Unix file management commands I'll be using - which will also be familiar to you macOS users out there, the actual Hugo commands and configuration files will work for everyone.
I'm actually working on a virtual LXD container on my workstation, so this is a remote shell. A bit later, we'll need to be aware that its IP address is 10.0.3.14. Keep that in mind. But if you're running Hugo directly on your machine, that extra addressing won't be necessary.
With Hugo successfully installed, I'm going to start by initializing a new site right below my current directory using hugo new site. I'll give this site the name example. That'll output some "getting started" instructions and create a directory with the name example.
I'll just change directory into example and list the current contents. Notice the content, public, static, and themes directories. content is where we'll place the MarkDown text files that Hugo will eventually convert to HTML. public is where Hugo will create those new files - along with other resources - when it eventually generates each version of our site. Once your development work is complete, public is where you'll find the all the website resources you'll need to upload to your S3 bucket. static is where, in just a moment, I'll save an image file to be loaded with my HTML. And themes is, as I'm sure you can guess, where the resources used by one or more site themes are kept. The one regular file in this directory - config.toml - is where many site configurations are made. We'll get back to that one, soon.
But first, let's install a theme. You can create your own custom theme if you like, but there are also hundreds of open source themes available for you from the GoHugo.io site. As you can tell from the tags on the right, there are twenty or so categories of themes, that can help you choose one that's a good fit for your project. Take some time to browse through them on your own. I used the Mainroad theme for my Teach Yourself Data Analytics site, if you're curious.
That will start with the git init command. I'm assuming, of course, that you've already got git installed on your machine. I'll then use git to add a submodule by downloading the contents of that GitHub repo and then copying them to the themes/ananke directory. To incorporate the theme into our project, I'll edit that config.toml file by adding the line theme = "ananke". That's it. Naturally, for a more serious project, I'd edit the baseURL value to reflect my domain name, and probably give the site a better title. For now, though, I'll just save this file.
Now I'm going to switch to a second shell session on the same machine and change directory into example. Hugo includes a server that lets us test our site even while it's in development without the need to build a production server. I can launch that server using the hugo server command. Because I'm going to want to view the site on my local browser, I'll need to add the bind argument, pointing to my container's IP address. But, again, if you're working locally on your machine, you'll leave this part out.
Note the connection instructions that are displayed. If you were doing this locally, you'd just type localhost:1313 into your browser URL bar. But I type the IP address and that 1313 port instead. And there's our beautiful site!
Let's see if we can't make it even nicer. I'll open the config.toml file again in that other shell session and edit the title. Watch carefully. As soon as I save the file with its changes, the updates will appear in the browser. The new title happens to show up in three different places on the page, but all of those can be controlled through customizations.
Here's an example of a config.toml file:
baseURL = "https://stories.thedataproject.net"
languageCode = "en-us"
title = "Teach Yourself Data Analytics in 30 Days"
theme = "mainroad"
relativeURLS=true
[Params]
toc = true # Enable Table of Contents
[Params.sidebar]
home = "right" # Configure layout for home page
list = "left" # Configure layout for list pages
single = true # Configure layout for single pages
# Enable widgets in given order
widgets = ["search", "recent", "categories", "taglist", "social", "languages"]
# alternatively "ddg-search" can be used, to search via DuckDuckGo - "search" uses Google
# widgets = ["ddg-search", "recent", "categories", "taglist", "social", "languages"]
[menu]
[[menu.main]]
pre = "<i class='fa fa-heart'></i>"
weight = -110
[[menu.main]]
identifier = "Purchase"
name = "Buy the book"
pre = "<i class='fa fa-heart'></i>"
url = "https://amzn.to/3uq9HuQ"
weight = -110
[[menu.main]]
identifier = "SignUp"
name = "Newsletter Sign Up"
pre = "<i class='fa fa-heart'></i>"
url = "https://thedataproject.net/index.php/stay-in-touch"
weight = -110
[[menu.main]]
identifier = "Home"
name = "The Data Project"
pre = "<i class='fa fa-heart'></i>"
url = "https://thedataproject.net"
weight = -110
```