Before you begin

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

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

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)