Before you begin
The example site’s pinned npm dependencies
provide Hugo and Dart Sass, so if that’s your starting point, skip those
sections: install only Go,
Git, and Node.js. On Windows,
also ensure that Bash is on your PATH: the example site’s npm scripts run
under Bash, which ships with Git for Windows.
Install Hugo
You need a recent extended version of Hugo, version
0.160.1 or later, to build and preview sites that use
Docsy. Check your version, and ensure that the output mentions extended:
hugo version
To install or upgrade, see Install Hugo. If you install from the Hugo releases page, pick an extended asset; you may need to scroll down the list of releases to see it.
For the tool versions that Docsy officially supports, see Official support.
As an npm module
You can conveniently install any Hugo version using hugo-extended (replace
latest with the version you want to install):
npm install hugo-extended@latest --save-dev
Install Dart Sass
This section applies to all installation options, not just Hugo-module setups.
Hugo compiles Docsy’s SCSS using the Dart Sass transpiler, which Hugo
looks up as the sass CLI on its PATH. For npm-based sites, install the
sass-embedded package from your project root, at the version
Docsy is tested with:
npm install --save-exact --save-dev sass-embedded@1.102.0
Installing sass-embedded also adds @parcel/watcher, an install-script
package, to your lockfile: it arrives through the optional pure-JS fallback
and is never installed or run on platforms with a prebuilt sass-embedded
binary. Projects that review or gate install scripts can deny it.
The sass CLI is then on PATH for every npm-run script, so run Hugo through
npm scripts. For example, with the following in your package.json:
{
"scripts": {
"hugo": "hugo"
}
}
run any Hugo command as npm run hugo -- ARGS, for example
npm run hugo -- server to serve your site locally.
For non-npm setups, see Hugo’s Dart Sass installation guide. For the officially supported Dart Sass version, see Official support.
Install Go language
Hugo’s module management requires the Go language, version 1.18 or later, per Hugo’s requirements. Check your version:
$ go version
go version go1.25.6
To install or upgrade Go, use the Go download page.
Install Git VCS client
Hugo’s module management also requires the Git client. Check your version:
$ git version
git version 2.52.0
To install or upgrade Git, use the Git download page.
Install Node.js
Docsy sources its Bootstrap and Font Awesome assets from npm, so you need
Node.js (which provides npm, the Node package manager)
to install them. Install or upgrade to the active long-term support (LTS)
release (consider using nvm to install and manage Node versions),
then check your version:
node -v
Install PostCSS (optional)
This section applies to all installation options, not just Hugo-module setups.
Docsy builds its CSS without PostCSS by default – the
shipped CSS targets the Browserslist defaults
browsers – so most sites don’t need it. Install PostCSS only if:
- Your site has a right-to-left (RTL) language, or
- You post-process your own CSS with a project-root
postcss.config.{js,mjs,cjs}file.
If either applies, install PostCSS from your project root:
npm install --save-dev autoprefixer postcss-cli
npm also installs postcss itself, as a peer dependency of the packages
listed above. If you use a package manager that doesn’t auto-install peer
dependencies, such as Yarn, add postcss to the install command.
What’s next?
With all prerequisites installed, choose how to start off with your new Hugo site
Feedback
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.