Initial Setup

Required Installations

There are only 2 tools needed to get started contributing to the documentation:

  1. hugo version 0.93 or newer.
  2. git

Installing Hugo

For this guide, we’re going to cover the easiest way to install hugo, which is downloading an already built executable. If you would prefer to install from a package manager like brew, chocolately, or apt, then you should follow along with the corresponding installation guide from hugo’s documentation.

First you’ll want to navigate to the releases page for hugo. You’ll be greeted with a bunch of text describing the latest release.

Releases Page

Note: the version number might not match.

From there you’ll want to scroll down until you see a heading called Assets.

Assets for download

From here, you’ll want to click on build for your system to download it.

Installing the Executable

If you’re on a Windows computer, you need to know how many bits the operating system is, and what kind of processor you’re running.

If you’re unsure of these things, you can find them by:

  1. Opening the Settings App.
  2. Navigate to System, then About
  3. The details are available under the System type value.

Using those details you should install your corresponding version.

  • 64-bit - x64: hugo_<ver>_Windows-64bit.zip
  • 64-bit - ARM: hugo_<ver>_Windows-ARM64.zip
  • 32-bit - x86: hugo_<ver>_Windows-32bit.zip
  • 32-bit - ARM: hugo_<ver>_Windows-ARM.zip

Then make a new folder called C:\Hugo\bin.

Move the downloaded .zip file into the newly created C:\Hugo\bin folder. Then double click on the .zip file and extract its contents. The folder should now contain the following 3 new files:

  • hugo.exe
  • LICENSE
  • README.md

From here, we’re going to need to add hugo to your Windows PATH settings to know that hugo means to run the hugo.exe program in this folder. To do this in Windows 10, you’ll need to go through the following steps:

  1. Right click on the Start button.
  2. Click on System.
  3. Click on Advanced System Settings
  4. Click on the button that says Environment Variables… on the bottom
  5. Click on the button that says Browse…, and select the C:\Hugo\bin folder.
  6. Click OK on all following windows.

Using Package Managers

Alternatively, you can use the following if you have Chocolately installed.

choco install hugo -confirm

Or the following if you have Scoop installed.

scoop install hugo

Installing the Executable

If you’re on a Mac with an Intel Processor, you should use hugo_<ver>_macOS-64bit.tar.gz.

If you’re on a Mac with an M1/M2 Processor, you should use hugo_<ver>_macOS-ARM64.tar.gz.

Once you’ve downloaded the corresponding release, we’ll need to open up a Terminal, and start by making a folder for the hugo program.

mkdir -p ~/bin

Then we’re going to navigate into it.

cd ~/bin

From here, we’re going to extract the downloaded release into this folder.

tar -xvzf ~/Downloads/hugo_<ver>_macOS-<ARCH>.tar.gz

Where <ver> is going to match the version you downloaded, and <ARCH> will match given then processor in your Mac.

After this, we’re going to check if hugo is in your path by running:

which hugo

If there’s no answer, that means we have to add it to your path.

First we’ll need to see which shell you’re working with by running:

echo $SHELL

If the answer is zsh, you’ll want to run:

echo "export PATH=$PATH:$HOME/bin" >> ~/.zprofile

and if the answer is bash you’ll want to run:

echo "export PATH=$PATH:$HOME/bin" >> ~/.bash_profile

Finally close your terminal. When opening a new terminal, hugo will be ready to use.

Using Package Managers

Alternatively, you can also run the following if you have Homebrew installed.

brew install hugo

Or the following if you have MacPorts installed.

port install hugo

If you’re on Linux/OpenBSD, it’s highly recommended you use a package manager install hugo since it does not require a new install like in Windows and Mac.

Debian, Ubuntu

snap install hugo

Arch

sudo pacman -Syu hugo

Fedora, Red Hat, CentOS

sudo dnf install hugo

openSUSE Tumbleweed

sudo zypper install hugo

OpenBSD

doas pkg_add hugo

Install git

You’ll want to download and install the corresponding Git for Windows Setup, depending on if your system is 32 or 64 bit. Instructions for how to do so can be found in the section above for installing hugo.

From a terminal run

git --version

If it’s not installed, you’ll be prompted with an installer.

Debian, Ubuntu

sudo apt install git

Arch

sudo pacman -Syu git

Fedora, Red Hat, CentOS

sudo dnf install git

openSUSE Tumbleweed

sudo zypper install git

OpenBSD

doas pkg_add git

While this is everything you need to get up and editing the documentation site, if you’re used to working in something like Google Docs or Microsoft Word, I’d recommend getting setup with an environment that will take care of content editing, managing git changes, and running the hugo commands all in one place. If you’d prefer to use your own tools, know that you’ll be expected to do the following:

  • Start and stop the hugo live server from the command line.
  • Manage git changes and commits from the command line.
  • Edit Markdown files directly from a text editor, not a document editor like Word or Docs.

If you already have a text editor of choice, vim, emacs, sublime etc, I recommend checking out the following page for plugins that will help with working with hugo.

If you don’t have a text editor of choice, I’d recommend installing Visual Studio Code. It comes built with the tools we need to work with hugo and git without having to resort to a command line.

Once you have Visual Studio Code installed, you’ll want to launch it and install the following plugins: