How to Install Hugo and Blowfish (without losing your mind)

What is Hugo?

#

If you’re looking for something to manage a blog, documentation, or just a website where you can publish your stuff, and you’ve realized that WordPress is slow, insecure, and you’re sick of updating plugins every two days just to stop the Russians or Chinese from breaking in…

The solution is Hugo. It’s a static site generator built in Go. It compiles your entire website in milliseconds. But before you start, you need to know that the pages you generate will be written in Markdown, or, if you’re too scared to use the Linux terminal even a little bit, then quit now and go use Wix.

Aside from Hugo, I’m going to show you how to install the Blowfish theme, which is the one I currently use.

Requirements

#

I’m going to teach you how to install Hugo on Linux and host it on GitHub Pages, so you need:

• A GitHub account.
  • Since we’re using GitHub, you obviously need to have Git installed on your machine.
• A code editor.
  • You can use Gedit, Visual Studio, Sublime Text, or even nano or vim if that works for you. Use whatever you know. I recommend Visual Studio Code.

Installation

#

With Snap Store

#

There are several ways to install Hugo; the first and easiest one, if you have Snap, is to paste the following command into your terminal:

sudo snap install hugo --channel=extended

We need the Extended version for Sass/SCSS support.

The General Way for Linux

#

If you don’t have Snap, or you just don’t feel like using it, you can download the .deb package from the official Hugo repository.

Go to GitHub Releases. Look for the .deb file that says hugo_extended_X.XX.X_linux-amd64.deb. It is crucial that it includes the word extended.

Once you have the .deb, download it manually or use wget <download link>.

To install it, navigate to the directory where you have the .deb and execute:

sudo dpkg -i hugo_extended_*.deb

Now, to check that everything went well, close your current terminal, open a new one, and run:

hugo version

You should see something like:

umar@crappycomputer:~$ hugo version
hugo v0.155.3-8a85c04d295+extended linux/amd64 (...)

With this, you now have Hugo on your machine.

Your First Website

#

Now that you have Hugo, let’s create your website, blog, portfolio, or whatever the hell it’s for. The key command here is the following, where my-blog will be the name of the folder Hugo creates for your site.

hugo new site my-blog

Now that you have it, go inside and initialize your repo:

cd my-blog
git init

Create and Connect the GitHub Repository

#

Before continuing, you need to create a repository on GitHub and connect it to your local repo.

Go to GitHub and create a new repository.

When you create the repo, DO NOT check the options for “Add a README file”, “.gitignore”, or “license”. Leave it empty because you already have the local content. Also, if you don’t have GitHub Pro, the repo must be public.

Once the repo is created, copy the URL GitHub gives you (something like https://github.com/your-username/repo-name.git) and run:

git remote add origin https://github.com/your-username/repo-name.git

Installing the Blowfish Theme

#

Now we’re going to install the Blowfish theme; it’s a theme with a lot of possibilities, and I think it’s great for a first site. However, if you have something else in mind and want to use another theme, you can search for whatever you like in the Hugo themes repository.

We could download the zip and add it manually, but use the following command to get the latest version of Blowfish:

git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

Blowfish has a complex configuration due to the different possibilities it offers. I do not recommend starting from scratch writing .toml files, or you will definitely break something. Copy the example files from themes/blowfish/config/_default/ to your config/_default/ folder. You might need to create the folders yourself.

Then edit hugo.toml and change the baseURL:

baseURL = "https://docs.umarmohammad.xyz/"
languageCode = "en"
theme = "blowfish"
title = "Umar Mohammad Docs"

In my configuration, I put the URL https://docs.umarmohammad.xyz/, but you might not have your own domain. In that case, since you are going to use GitHub Pages, you should put github-username.github.io. That way, to access your site, someone will type github-username.github.io in their browser.

If you have your own domain, I’ll also teach you how to configure the DNS in the next steps. For now, as a recommendation, don’t modify the theme or Hugo settings too much; you might screw it up 😵.

Local Testing

#

Now, before moving on, let’s test if our local repository works. In the website directory, run:

hugo server

Open http://localhost:1313 in your browser; if it works, congratulations. If not, read the error log in the terminal. At this point, it’s probably a stupid configuration error from touching the hugo.toml file.

Deploying with GitHub Pages

#

Okay, now comes the fun part so anyone can access your site. First, from the terminal, make sure you are in your site’s directory if you weren’t already, and run:

# Add everything to staging
git add .

# Commit
git commit -m "First commit of my site with Hugo"

# Push to the repo
git branch -M main
git push -u origin main

Now go to the repository on the web: GitHub → Settings → Pages. Next, you’ll see the Build and deployment option, and right below that, Source with a dropdown menu; we are interested in selecting the GitHub Actions option.

Now, under the dropdown where you selected GitHub Actions, browse all workflows should appear. If you click it, search for hugo, hit Enter, and select Hugo by clicking Configure.

Next, you will see a page very similar to the following one. The only thing you need to modify here is to go down to line 34, where it indicates HUGO_VERSION, and put the version you installed earlier on your local machine.

If you don’t do this step, you will very likely have problems later with the themes and settings you use. Once this is done, you must click on Commit changes.

After making these adjustments, the next step you must take is to pull the changes from GitHub Actions to your local repo with the following command:

git pull

Now, this step is important: if you are going to use a custom domain, you must execute the following with your domain:

echo "domain.com" > static/CNAME

git add .

git commit -m "CNAME record"

git push origin main

With this step, you just have to wait 2-3 minutes for GitHub Actions to launch your website on your custom domain or on your-username.github.io. Now you can access your website.

Finally, to create content, I recommend opening the local repo folder with VSCode and installing the Front Matter CMS extension, which will simplify your life.

And also visit the documentation for Hugo and Blowfish to learn more.