Before you begin

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

Install Hugo

You need a recent extended version (version 0.110.0 or later) of Hugo to do local builds and previews of sites (like this one) that use Docsy. 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.

On Linux

Be careful using sudo apt-get install hugo, as it doesn’t get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

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 install the latest version. You can see a complete list of Linux installation options in Install Hugo. The following shows you how to install Hugo from the release page:

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 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)