Get started

• 1: Use Docsy as a Hugo Module
• 1.1: Before you begin
• 1.2: Create a new site: start with a prepopulated site
• 1.3: Create a new site: start a new site from scratch
• 2: Other setup options
• 3: Basic site configuration
• 4: Troubleshooting and known issues

1 - Use Docsy as a Hugo Module

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.1 - 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)

1.2 - Create a new site: start with a prepopulated site

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.

If you prefer to create a site from scratch, follow Start a site from scratch.

TL;DR: Setup for the impatient expert

With the prerequisites installed (on Windows, including Bash on your PATH), run:

git clone --depth 1 --branch v0.16.0 https://github.com/google/docsy-example.git my-new-site
cd my-new-site
npm run install:safe
npm run serve

Preview at http://localhost:1313/. If the build fails, see Troubleshooting.

Detailed Setup instructions

Clone the Docsy example site

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:

git clone --depth 1 --branch v0.16.0 https://github.com/google/docsy-example.git my-new-site

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.

1. Go to the repo of the Docsy example site.

2. Click the button Use this template and select the option Create a new repository from the dropdown.

3. 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.

4. Click Create repository from template to create your new repository.

5. Make a local copy of your newly created GitHub repository by using git clone, giving your repo’s web URL as last parameter.

   git clone https://github.com/me-at-github/my-new-site.git
   

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.

What’s next?

• Add some basic configuration
• Edit existing content and add more pages
• Customize your site
• Publish your site.

1.3 - Create a new site: start a new site from scratch

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:

• CLI:
• Unix shell
• Windows command line

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.16.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy/theme"
EOL
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

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.16.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

Preview at http://localhost:1313/.

Detailed Setup instructions

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).

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.16.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.

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[module]
  proxy = "direct"
  # uncomment line below for temporary local development of module
  # replacements = "github.com/google/docsy/theme -> ../../docsy/theme"
  [module.hugoVersion]
    extended = true
    min = "0.160.1"
  [[module.imports]]
    path = "github.com/google/docsy/theme"
    disable = false

module:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.160.1
  imports:
    - path: github.com/google/docsy/theme
      disable: false

{
  "module": {
    "proxy": "direct",
    "hugoVersion": {
      "extended": true,
      "min": "0.160.1"
    },
    "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.

What’s next?

• Add some basic configuration
• Add content and customize your site
• Get some ideas from our Example Site and other Examples and templates.
• Publish your site.

2 - Other setup options

If Docsy as a Hugo Module doesn’t suit your site – for example, if you don’t want to install Go – choose from these setup options:

• Option 1: Docsy as a Git submodule
• Option 2: Clone the Docsy theme
• Option 3: Docsy as an NPM package

Prerequisites

Install Hugo

You need a recent extended version of Hugo, version 0.160.1 or later. For installation options, including the npm-managed hugo-extended package, see Install Hugo.

Install Node.js

Install or upgrade to the active Node.js LTS release, as explained in Install Node.js.

Install Dart Sass

See Install Dart Sass, including its recommendation to run Hugo through npm scripts, which have the sass CLI on their PATH automatically.

Install PostCSS (optional)

See Install PostCSS.

Option 1: Docsy as a Git submodule

If you are using Docsy as a Git submodule but would like to migrate to Hugo Modules, see our migration guide.

For a new site

To create a new site and add the Docsy theme as a Git submodule, run the following commands:

1. Create the site:

   hugo new site myproject
   cd myproject
   git init
   

2. Follow the instructions below for an existing site.

For an existing site

To add the Docsy theme to an existing site, run the following commands from your project’s root directory:

1. Install Docsy as a Git submodule:

   git submodule add https://github.com/google/docsy.git themes/docsy
   git -C themes/docsy checkout v0.16.0
   

   To work from the development version of Docsy (not recommended), run the following command instead:

   git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy
   

2. Add Docsy as a theme, for example:

   echo 'theme: docsy/theme' >> hugo.yaml
   

3. Get Docsy dependencies:

   (cd themes/docsy && npm run install:theme-deps)
   

   Note

   Run npm run install:theme-deps, not npm install: install:theme-deps installs only the theme’s runtime dependencies, lock-pinned and script-free; a plain npm install inside themes/docsy/ also pulls the repository’s maintainer workspaces, an install more than an order of magnitude larger.

4. (Optional but recommended) To avoid having to repeat the previous step every time you update Docsy, consider adding NPM scripts like the following to your project’s package.json file:

   {
     "...": "...",
     "scripts": {
       "get:submodule": "git submodule update --init --depth 1",
       "_prepare:docsy": "cd themes/docsy && npm run install:theme-deps",
       "prepare": "npm run get:submodule && npm run _prepare:docsy",
       "...": "..."
     },
     "...": "..."
   }
   

   Every time you run npm install from your project root, the prepare script restores the submodule at its recorded revision and installs the theme’s dependencies.

From this point on, build and serve your site with Hugo, run through npm scripts (see the prerequisites), for example:

npm run hugo -- server

Option 2: Clone the Docsy theme

If you don’t want to use submodules (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project’s themes subdirectory.

To clone Docsy at v0.16.0 into your project’s themes folder, run the following commands from your project’s root directory:

cd themes
git clone -b v0.16.0 https://github.com/google/docsy
cd docsy
npm run install:theme-deps

As with the submodule option, set theme: docsy/theme in your site configuration. The note above about npm run install:theme-deps versus npm install applies here as well.

To work from the development version of Docsy (not recommended unless, for example, you plan to upstream changes to Docsy), omit the -b v0.16.0 argument from the clone command above.

Then consider setting up an NPM prepare script that installs the theme’s dependencies, like the _prepare:docsy script in Option 1’s example (the submodule step doesn’t apply to a clone).

For more information, see Theme Components on the Hugo site.

Option 3: Docsy as an NPM package

Docsy is published to the npm registry as @docsy/theme. To create a new site that uses the Docsy NPM package:

1. Create your site:

   hugo new site --format yaml myproject
   cd myproject
   

2. Install Docsy along with the Dart Sass compiler, at the version Docsy is tested with, and define an npm script for running Hugo:

   npm init -y
   npm install --save-dev @docsy/theme
   npm install --save-exact --save-dev sass-embedded@1.102.0
   npm pkg set scripts.hugo=hugo
   

   Hugo install tip

   To also install Hugo as an NPM package, see As an npm module.

3. Add Docsy as your site’s theme by including the following in your project’s hugo.yaml:

   theme: '@docsy/theme'
   themesDir: node_modules
   

4. Build or serve your new site with Hugo, run through npm scripts (see the prerequisites). For example, build your site as follows:

   $ npm run hugo
   Start building sites …
   ...
   

To update Docsy later, see Update your Docsy NPM package.

Development versions of Docsy

Use only official Docsy releases in production. For Docsy development or testing, you can also install:

• A pre-release, when one is available, through the next dist-tag:

  npm install --save-dev @docsy/theme@next
  

• Docsy directly from GitHub:

  npm install --save-dev google/docsy
  (cd node_modules/docsy && npm run install:theme-deps)
  

  This installs the repository’s default branch (main). To pin a tagged version:

  npm install --save-dev google/docsy#semver:v0.16.0
  

  For other revision selectors, see npm install. The GitHub package is named docsy and contains the theme files in a subfolder, so with this install form use theme: docsy/theme in your site configuration. Unlike the registry package, the GitHub package doesn’t declare Bootstrap and Font Awesome as its own dependencies: the install:theme-deps command installs them, and must be rerun after every install or update of the package.

Preview your site

To preview your site locally, run Hugo through an npm script (see the prerequisites):

cd myproject
npm run hugo -- server

By default, your site will be available at http://localhost:1313. For common issues, see Troubleshooting. If the build fails with missing-parameter errors, add the required defaults per Basic site configuration.

What’s next?

• Add some basic site configuration
• Add content and customize your site
• Get some ideas from our Example Site and other Examples and templates.
• Publish your site.

3 - Basic site configuration

Site-wide configuration details and parameters are defined in your project’s configuration file (hugo.toml or config.toml). These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in hugo.yaml in the example project for how to add this information. We recommend copying this hugo.yaml and editing it even if you’re just using the theme and not copying the entire Docsy example site, as it includes default values for many parameters that you need to set for your site to build correctly.

You may want to remove or customize some defaults of the copied hugo.toml file straight away:

Internationalization

The copied hugo.toml file defines content in English, Norwegian and Farsi. You can find out more about how Docsy supports multi-language content in Multi-language support.

If you don’t intend to translate your site, you can remove the language switcher by removing the following lines from hugo.toml:

[languages.no]
label = "Norsk"
contentDir = "content/no"
[languages.no.params]
title = "Goldydocs"
description = "Docsy er operativsystem for skyen"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"

[languages.fa]
label = "فارسی"
contentDir = "content/fa"
[languages.fa.params]
title = "اسناد گلدی"
description = "یک نمونه برای پوسته داکسی"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"

Search

By default, the Docsy example site uses its own Google Custom Search Engine. To disable this site search, delete or comment out the following lines:

# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "..."

To use your own Custom Search Engine, set gcs_engine_id to your search engine ID. For details, see Configure search with a Google Custom Search Engine.

What’s next?

• Add content and customize your site
• Get some ideas from our Example Site and other Examples and templates.
• Publish your site.

4 - Troubleshooting and known issues

Troubleshooting

Missing theme npm dependencies

For any Docsy install mode, if the theme’s npm packages aren’t available, Hugo fails while compiling SCSS with an error like:

TOCSS: failed to transform "/scss/main.scss" (text/x-scss):
File to import not found or unreadable: ../../vendor/bootstrap/scss/functions.

To fix this, install the theme’s npm dependencies for your setup, then rebuild:

• Example-site-based projects: run npm run install:safe from your site root; in an older copy without that script, use your repository’s own install script.
• Sites using Docsy as an NPM package: install from your site root, for example with npm install.
• Hugo module sites built from scratch: see Install npm dependencies.
• Sites using Docsy as a Git submodule or a cloned theme: run npm run install:theme-deps from themes/docsy.

Missing Dart Sass compiler

If Hugo can’t find the Dart Sass sass CLI on its PATH, it fails while compiling SCSS with an error like:

TOCSS-DART: failed to transform "scss/main.scss" (text/x-scss).

To fix this, follow Install Dart Sass, then rebuild.

Known issues

The following issues are known on MacOS and on Windows Subsystem for Linux:

MacOS

Errors: too many open files or fatal error: pipe failed

By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications, you might receive one of the following errors when you run hugo server to preview your site locally:

• POSTCSS v7 and earlier:

  ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
  

• POSTCSS v8 and later:

  fatal error: pipe failed
  

Workaround

To temporarily allow more open files:

1. View your current settings by running:

   sudo launchctl limit maxfiles
   

2. Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can choose to set lower soft (65535) and hard (200000) limits.

   sudo launchctl limit maxfiles 65535 200000
   ulimit -n 65535
   sudo sysctl -w kern.maxfiles=200000
   sudo sysctl -w kern.maxfilesperproc=65535
   

Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.

Windows Subsystem for Linux (WSL)

If you’re using WSL, ensure that you’re running hugo on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.