Setting Up a Site With Hugo

- 6 mins read

Intro

You don’t need to read this part really :3 Just me blabing. I wrote this as I installed and setup Hugo for the first time and documented issues I had along the way. Despite it being documentation for myself, this can also be used as a guide! I decided to use Hugo because I wanted to create a blog section for my website. I tried using Jekyll but I’m not a fan of Ruby. Also, Jekyll and its documentation felt dated compared to Hugo; which is written in Go. Being a fan of Rust I also looked at Zola; However Hugo felt like a better fit. At the end there is an install script.

[!note] The $ denotes a terminal command. Anything before $ denotes the current working directory.

[!tip] Always update && upgrade your system first! ~$ sudo apt update && sudo apt upgrade -y

Install Hugo to Host

  • If you wish to do development on this device, you will want to do the full installation of Hugo on the host for viewing quick updates. Otherwise, the standard version is all you need so you can initialize the Hugo directory for your website. ~$ sudo apt install hugo

[!warning] Apt installs version 0.92.2

This is older than the required (at least) v0.112.0 of Hugo. It is annoying how many packages in apt are so old. I had this issue with Jekyll and NodeJS on other projects; creating many headaches. I will consider switching my server to Arch Linux in the future. For now I will remove Hugo and install and build directly from GitHub.

  • Remove Hugo if installed ~$ sudo apt autoremove hugo

Prerequisites

[!note] There is an automated script here: [[#Automated Install Script]]. Continue reading though! You may not want to use this on your host machine!

Install Go

  1. Download Go ~$ wget https://go.dev/dl/go1.23.1.linux-amd64.tar.gz
  • Remove any existing Go installations and expand the archive in /usr/local/. Un-taring the archive into an existing /usr/local/go tree is known to produce broken Go installations.
~$ sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.1.linux-amd64.tar.gz
  1. Add /usr/local/go/bin/ to the PATH environment variable ~$ export PATH=$PATH:/usr/local/go/bin
  2. Verify installation ~$ go version

Install Dart Sass

  1. Download and expand the Linux-x64.tar release from GitHub
~$ wget https://github.com/sass/dart-sass/releases/download/1.78.0/dart-sass-1.78.0-linux-x64.tar.gz && sudo tar -C /usr/local -xzf dart-sass-1.78.0-linux-x64.tar.gz
  1. Add /usr/local/dart-sass to the PATH environment variable
~$ export PATH=$PATH:/usr/local/dart-sass
  1. Verify installation
~$ sass --version

Clean up!

~$ rm go1.23.1.linux-amd64.tar.gz dart-sass-1.78.0-linux-x64.tar.gz

Build and install Hugo

  1. Build the extended edition:
~$ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
  1. Add the /go/bin PATH environment variable. You can move this go directory somewhere else if you wish; Just be sure to correctly configure your environment variables now and in the future. ~$ export PATH=$PATH:~/go/bin
  2. Verify installation ~$ hugo version

Create a Docker Container (recommended)

Install Docker

https://docs.docker.com/engine/install/

Create Dockerfile

This is based upon the install script

# Use Golang base image
FROM golang:alpine

# Install dependencies for Hugo extended version and Sass/SCSS support
RUN apk add --no-cache git gcc g++ musl-dev libc-dev curl

# Install Dart Sass
RUN wget https://github.com/sass/dart-sass/releases/download/1.78.0/dart-sass-1.78.0-linux-x64.tar.gz && \
    tar -C /usr/local -xzf dart-sass-1.78.0-linux-x64.tar.gz && \
    rm dart-sass-1.78.0-linux-x64.tar.gz

# Add Dart Sass to PATH
ENV PATH="/usr/local/dart-sass:${PATH}"

# Install Hugo extended version
RUN CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest

# Install hugo-obsidian for the theme
RUN go install github.com/jackyzha0/hugo-obsidian@latest

# Set working directory
WORKDIR /hugo-site

# Copy site data into the image
COPY hugo-site /hugo-site

# Expose port for Hugo server
EXPOSE 1313

# Command to run Hugo server
CMD ["hugo", "server", "--bind", "0.0.0.0", "--watch", "--cleanDestinationDir", "--disableFastRender"]

Install Hugo (any) on the Host

We need to create a directory for our new Hugo site to live on. We can of course do this manually but that would be silly. For this purpose alone we can simply install using apt. However, if you wish to develop on the current machine you will want to do a full install. For that, follow [[#Prerequisites]] or use the install script: [[#Automated Install Script]]. Read more below as to why.

Initialize the website!

  1. Create directory structure in the my-site directory and change into that directory ~$ hugo new site my-site ~$ cd my-site

  2. Initialize a Git repo ~$ git init

  3. Set a theme. In this case, ‘ananke’ ~$ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke $ echo "theme = 'ananke'" >> hugo.toml

  4. Start the development server to view the new website ~$ hugo server

    [!info] When running this there is a warning: deprecated: resources.ToCSS was deprecated in Hugo v0.128.0 and will be removed in a future release. Use css.Sass instead. To work around this, you can add ignoreLogs = ['error-remote-getjson'] to your config.toml

    • Yay! We can see something on http://localhost:1313/ :]

Add Content

Development Server

  • Start the development server ~/hugo-docker/hugo-site$ sudo ~/.go/bin/hugo server -D or ~/hugo-docker/hugo-site$ ~/.go/bin/hugo server --buildDrafts Hugo is not installed for the root user and many files in the site directory are now owned by the current user. To work around this for development, we will just point to the file path of the Hugo binary and run it that way.
  • Starting in development mode will allow you to see updates to your site as you make them and save http://localhost:1313/

Live Remote Server

  1. Build the Docker container ~/hugo-docker$ docker build -t my_image .
  2. Push the Docker container to Docker Hub
    1. Log into Docker ~/hugo-docker$ docker login
      • You will be prompted to login via the web with a one time login code
    2. Add a tag to the image (the following is just an example) ~/hugo-docker$ docker tag my_image:latest myusername/my_image:latest
    3. Push the image ~/hugo-docker$ docker push myusername/my_image:latest
  3. Connect to your server
  4. Pull your new Docker image from Docker Hub (login if necessary) 
    ~/$ docker pull USERNAME/REPOSITORY_NAME:TAG
    • Ensure the image pulled successfully
    ~/$ docker images
  5. Start the container
    • There are many different ways to do this. I will start my container dethatched with persisting data in a directory I made called Docker
    ~/$ docker run -dp 1313:1313 IMAGE_ID
    • or
    ~/$ docker run -dp 1313:1313 IMAGE_NAME:TAG

Configure the Site

  • That’s it! Add content and change the theme to look exactly as you wish!

Automated Install Script

References

Hugo

GoLang

Sass

Music I listened to while doing this