Before you begin
This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.
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.
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:
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:
Go to the Hugo releases page.
In the most recent release, scroll down until you find a list of Extended versions.
Download the latest extended version (
Create a new directory:
Extract the files you downloaded to
Switch to your new directory:
sudo install hugo /usr/bin
Install Hugo using Brew.
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
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.4
Ensure that you are using version 1.12 or higher.
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.42.1
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.
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 -D autoprefixer npm install -D postcss-cli
Starting in version 8 of
postcss-cli, you must also separately install
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.
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:
# 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
# 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 -
With all prerequisites installed, choose how to start off with your new Hugo site
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.