Hugo modules are the simplest and latest way
to use Hugo themes like Docsy when building a website. Hugo uses the modules
mechanism to pull in the theme files from the main Docsy repo at your chosen
revision, and it’s easy to keep the theme up to date in your site. Our example
site uses Docsy as a Hugo module.
To find out about other setup approaches, see our
Get started overview. If you want to migrate an existing
Docsy site to use Hugo Modules, see our
migration guide.
Setup options with Hugo Modules
To use Docsy as a Hugo Module, you have a couple of options:
Copy and edit the source for the
Docsy example site. This approach
gives you a skeleton structure for your site, with top-level and documentation
sections and templates that you can modify as necessary. The example site uses
Docsy as a Hugo Module.
Build your own site using the Docsy theme. Specify the
Docsy theme like any other
Hugo theme when creating or updating your site.
With this option, you’ll get Docsy look and feel, navigation, and other
features, but you’ll need to specify your own site structure.
If you’re a beginner, we recommend that you get started by copying our example
site. If you’re already familiar with Hugo or want a very different site
structure, you can follow our guide to start a site from scratch, which gives
you maximum flexibility at the cost of higher implementation effort. In both
cases you need to follow our prerequisites guide to make sure that you have
installed Hugo and all necessary dependencies.
1 - Before you begin
Hugo, Dart Sass, Go, Git, Node.js, and optional PostCSS requirements for Docsy sites
Note
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):
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:
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.
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:
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:
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
Note
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
2 - Create a new site: start with a prepopulated site
Clone the example site and adapt it: a ready-made site structure with a pinned toolchain.
The Docsy example site gives you a
skeleton structure for your site, with top-level and documentation sections and
templates that you can modify as necessary.
There are two routes to get a local clone of the example site:
Option 1: Using the command line (local copy only)
For a local copy or a non-GitHub remote, clone the released example site, giving
your chosen local repo name (here: my-new-site) as the last parameter:
Option 2: Using the GitHub UI (local copy + associated GitHub repo)
The example site is a template repository, so you can generate your own
GitHub repository from it. Note that a template copies the example site’s
default branch (main), which can be ahead of the latest release; for a
release-pinned start, use option 1.
Depending on your environment you may need to tweak the
module top-level settings
in your hugo.yaml slightly, for example by adding a proxy to use when
downloading remote modules.
Preview your site
To build and preview your site locally, switch to the root of your cloned
project, install the project dependencies, and serve the site:
cd my-new-site
npm run install:safe
npm run serve
Preview at http://localhost:1313/. Hugo reloads the preview as you edit. Press
Ctrl + c to stop the server. If the build fails, see Troubleshooting.
3 - Create a new site: start a new site from scratch
For experienced Hugo users who need a custom site structure
Creating a site from scratch gives you Docsy’s look and feel, navigation, and
other features, but you specify your own site structure. These instructions give
you a minimum file structure only, so that you build and extend your actual site
step by step.
TL;DR: Setup for the impatient expert
Run:
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy/theme@v0.17.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy/theme"
EOLnpm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy/theme@v0.17.0
(echo [module]^
proxy = "direct"^
[[module.imports]]^
path = "github.com/google/docsy/theme")>> hugo.toml
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server
To create a new Hugo site project and then add the Docsy theme as a Hugo module,
run the following commands from your project’s root directory.
hugo new site my-new-site
cd my-new-site
This will create a minimal site structure, containing the folders archetypes,
content, data, layouts, static, and themes and a configuration file
(default: hugo.toml).
Import the Docsy theme module as a dependency of your site
Only sites that are Hugo Modules themselves can import other modules. To turn
your site into a Hugo Module, run the following commands in your newly created
site directory:
hugo mod init github.com/me/my-new-site
This creates a go.mod file for your site’s module definitions.
Next declare the Docsy theme module as a dependency for your site.
hugo mod get github.com/google/docsy/theme@v0.17.0
This command adds the docsy theme module to your definition file go.mod and
records the module checksums in go.sum.
Add theme module configuration settings
Add the settings in the following snippet at the end of your site’s
configuration file (default: hugo.toml) and save the file.
[module]proxy="direct"# uncomment line below for temporary local development of module# replacements = "github.com/google/docsy/theme -> ../../docsy/theme"[module.hugoVersion]extended=truemin="0.160.1"[[module.imports]]path="github.com/google/docsy/theme"disable=false
You can find details of what these configuration settings do in the
Hugo modules documentation.
Depending on your environment you may need to tweak them slightly, for example
by adding a proxy to use when downloading remote modules.
Install npm dependencies
Install the Dart Sass compiler at the version Docsy is tested with, and
define an npm script for running Hugo (see Install Dart Sass). Docsy sources
its Bootstrap and Font Awesome assets from npm: generate the theme’s
npm-dependency workspace (see Hugo’s Node dependencies) and
install it:
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
Re-run hugo mod npm pack whenever you
update Docsy or otherwise edit package.json; Hugo
warns when the dependency set drifts. For background, see Bootstrap and Font
Awesome via npm in the 0.16.0 release notes.
Preview your site
To build and preview your site locally, run Hugo through the hugo npm script
you defined, which puts the sass CLI on Hugo’s PATH:
npm run hugo -- server
By default, your site will be available at
http://localhost:1313. For common issues, such as the
build failing with a missing Bootstrap import, see Troubleshooting. If the
build fails with missing-parameter errors, add the required defaults per
Basic site configuration.