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
Prerequisites for building a site with Docsy as a Hugo Module.
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.158.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
If you’ve already installed Hugo, check your version:
hugo version
If the result is 0.158.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:
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 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.25.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.52.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 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, then check your version:
node -v
You install these assets when you create your site, as described in the next
steps.
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
Create a new Hugo site by using a clone of the Docsy example site as your starting point.
The simplest way to create a new Docsy site is to use the source of the
Docsy example site as starting point.
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 automatically pulls in the Docsy theme as a
Hugo Module, so it’s easy to
keep up to date.
The Example Site gives you a good starting point
for building your docs site and is pre-configured to automatically pull in the
Docsy theme as a Hugo Module. There are two different routes to get a local
clone of the example site:
If you want to create a local copy only, choose option 1.
If you have a GitHub account and want to create a GitHub repo for your site go
for option 2.
Option 1: Using the command line (local copy only)
If you want to use a remote repository other than GitHub (such as
GitLab, BitBucket,
AWS CodeCommit,
Gitea) or if you don’t want a remote repo at all, simply
make a local working copy of the example site directly using git clone. As
last parameter, give your chosen local repo name (here: my-new-site):
Use the dropdown for switching branches/tags to change to the latest released
tag v0.15.1-dev.
Click the button Use this template and select the option
Create a new repository from the dropdown.
Choose a name for your new repository (e.g. my-new-site) and type it in the
Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository.
Congratulations, you just created your remote GitHub clone which now serves
as starting point for your own site!
Make a local copy of your newly created GitHub repository by using
git clone, giving your repo’s web URL as last parameter.
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 use hugo’s server command:
cd my-new-site
npm install
hugo server
Preview at http://localhost:1313/. Thanks to Hugo’s live preview, you can
immediately see the effect of changes that you are making to the source files of
your local repo. Use Ctrl + c to stop the Hugo server whenever you like. If
the build fails with a missing Bootstrap import, see Troubleshooting.
3 - Create a new site: Start a new site from scratch
Create a new Hugo site from scratch with Docsy as a Hugo Module
The simplest approach to creating a Docsy site is
copying our example site.
However, if you’re an experienced Hugo user or the site structure of our example
site doesn’t meet your needs, you may prefer to create a new site from scratch.
With this option, you’ll get Docsy look and feel, navigation, and other
features, but you’ll need to specify your own site structure.
These instructions give you a minimum file structure for your site project only,
so that you build and extend your actual site step by step. The first step is
adding the Docsy theme as a Hugo Module to
your site. If needed, you can easily update the module to the
latest revision from the Docsy GitHub repo.
TL;DR: Setup for the impatient expert
At your command prompt, run the following:
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.15.1-dev
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy/theme"
EOLhugo mod npm pack
npm install
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.15.1-dev
(echo [module]^
proxy = "direct"^
[[module.imports]]^
path = "github.com/google/docsy/theme")>> hugo.toml
hugo mod npm pack
npm install
hugo server
Specifying the Docsy theme as Hugo Module for
your minimal site gives you all the theme-y goodness, but you’ll need to specify
your own site structure.
Create your new skeleton project
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).
Tip
In Hugo 0.110.0 the default config base filename was changed to hugo.toml.
If you are using hugo 0.110 or above, consider renaming your config.toml to
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 two new files, go.mod for the module definitions and go.sum
which holds the checksums for module verification.
Next declare the Docsy theme module as a dependency for your site.
hugo mod get github.com/google/docsy/theme@v0.15.1-dev
This command adds the docsy theme module to your definition file go.mod.
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.158.0"[[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 theme npm dependencies
Docsy sources its Bootstrap and Font Awesome assets from npm. Consolidate the
theme’s npm dependencies into your project’s package.json and install them:
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.
You may get Hugo errors for missing parameters and values when you try to build
your site. This is usually because you’re missing default values for some
configuration settings that Docsy uses - once you add them your site should
build correctly. You can find out how to add configuration in
Basic site configuration - we
recommend copying the example site configuration even if you’re creating a site
from scratch as it provides defaults for many required configuration parameters.