Before you begin

This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.

Install Hugo

To do local builds and previews of sites (like this one) that use Docsy, you need an extended version of Hugo, version v0.110.0 or higher. If you install from the release page, make sure to get the extended Hugo version, which supports SCSS; you may need to scroll down the list of releases to see it.

For comprehensive Hugo documentation, see gohugo.io.

As of docsy version v0.7.0, hugo version v0.110.0 or higher is required. If you’ve already installed Hugo, check your version:

hugo version

If the result is v0.109.0 or earlier, or if you don’t see Extended, you’ll need to update to the latest version.

On Linux

You can see a complete list of Linux installation options in the official hugo documentation. Below the two most popular installation options are described:

Using hugo debian package

The following shows you how to install Hugo from the release page using prebuilt debian packages:

1. Go to the Hugo releases page.

2. In the most recent release, scroll down until you find a list of Extended versions.

3. Download the debian package of the latest extended version (hugo_extended_0.1XX.X_linux-architecture.deb) to a directory of your choice.

   wget https://github.com/gohugoio/hugo/releases/download/v0.1XX.X/hugo_extended_0.1XX.X_linux-architecture.deb
   

4. Install Hugo using dpkg tool from debian package management system:

   sudo dpkg --install hugo_extended_0.1XX.X_linux-architecture.deb
   

Using prebuilt binaries

The following shows you how to install Hugo from the release page using prebuilt binaries:

1. Go to the Hugo releases page.

2. In the most recent release, scroll down until you find a list of Extended versions.

3. Download the prebuilt binaries of the latest extended version (hugo_extended_0.1XX_Linux-64bit.tar.gz).

4. Create a new directory:

   mkdir hugo
   

5. Extract the files you downloaded to hugo.

6. Switch to your new directory:

   cd hugo
   

7. Install Hugo:

   sudo install hugo /usr/bin
   

On macOS

Install Hugo using Brew.

As an npm module

You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:

npm install hugo-extended --save-dev

See the hugo-bin documentation for usage details.

Install Go language

Hugo’s commands for module management require that the Go programming language is installed on your system. Check whether go is already installed:

$ go version
go version go1.21.6

Ensure that you are using version 1.12 or higher.

If the go language is not installed on your system yet or if you need to upgrade, go to the download area of the Go website, choose the installer for your system architecture and execute it. Afterwards, check for a successful installation.

Install Git VCS client

Hugo’s commands for module management require that the git client is installed on your system. Check whether git is already present in your system:

$ git version
git version 2.43.0

If no git client is installed on your system yet, go to the Git website, download the installer for your system architecture and execute it. Afterwards, check for a successful installation.

Install PostCSS

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:

npm install -D autoprefixer
npm install -D postcss-cli

Starting in version 8 of postcss-cli, you must also separately install postcss:

npm install -D postcss

Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.

Install/Upgrade Node.js

To ensure you can properly build your site beyond executing hugo server, you must have the latest long term support (LTS) Version of Node.js. If you do not have the latest LTS version, you may see the one of following errors:

Error: Error building site: POSTCSS: failed to transform "scss/main.css" (text/css): Unexpected identifier
#OR
/home/user/repos/my-new-site/themes/docsy/node_modules/hugo-extended/postinstall.js:1
import install from "./lib/install.js";
       ^^^^^^^

SyntaxError: Unexpected identifier
    at Module._compile (internal/modules/cjs/loader.js:723:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)

You can check your current Node.js version by running node -v. If you need to install a new version, see the following instructions:

• Debian and Ubuntu based distributions

  tl;dr:

  # Using Ubuntu
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  
  # Using Debian, as root
  curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
  apt-get install -y nodejs
  

• Enterprise Linux based distributions

  tl;dr:

  # As root
  curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
  
  # No root privileges
  curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
  

What’s next?

With all prerequisites installed, choose how to start off with your new Hugo site

• Start with a prepopulated site (for beginners)
• Start site from scratch (for experts)