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: Deploy Docsy inside a Docker container
• 4: Basic site configuration
• 5: 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

This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.

Install Hugo

You need a recent extended version (we recommend version 0.73.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

Be careful using sudo apt-get install hugo, as it doesn’t get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

If you’ve already installed Hugo, check your version:

hugo version

If the result is v0.73 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:

1. Go to the Hugo releases page.

2. In the most recent release, scroll down until you find a list of Extended versions.

3. Download the latest extended version (hugo_extended_0.9X_Linux-64bit.tar.gz).

4. Create a new directory:

   mkdir hugo
   

5. Extract the files you downloaded to hugo.

6. Switch to your new directory:

   cd hugo
   

7. Install Hugo:

   sudo install hugo /usr/bin
   

On macOS

Install Hugo using Brew.

As an npm module

You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:

npm install hugo-extended --save-dev

See the hugo-bin documentation for usage details.

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.17.6 windows/amd64

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.35.1.windows.1

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 PostCSS

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:

npm install -D autoprefixer
npm install -D postcss-cli

Starting in version 8 of postcss-cli, you must also separately install postcss:

npm install -D postcss

Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.

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

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

TL;DR: Setup for the impatient expert

At your Unix shell or Windows command line, run the following command:

git clone -b sandbox https://github.com/google/docsy-example.git my-new-site
cd  my-new-site
hugo server

You now can preview your new site in your browser at http://localhost:1313.

Detailed Setup instructions

Clone the Docsy example site

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

git clone -b sandbox https://github.com/google/docsy-example.git my-new-site

Option 2: Using the GitHub UI (local copy + associated GitHub repo)

As the Docsy example site repo is a template repository, creating your own remote GitHub clone of this Docsy example site repo is quite easy:

1. Go to the Docsy example site repo and click Use this template.

2. Chose 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.

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

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

Now you can make local edits and test your copied site locally with Hugo.

Preview your site

To build and preview your site locally, switch to the root of your cloned project and use hugo’s server command:

cd my-new-site
hugo server

Preview your site in your browser 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. See the known issues on MacOS.

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

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:

• 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@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
cat >> config.toml <<EOL
[module]
[[module.imports]]
path = "github.com/google/docsy"
[[module.imports]]
path = "github.com/google/docsy/dependencies"
EOL
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@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
(echo [module]^

[[module.imports]]^

path = "github.com/google/docsy"^

[[module.imports]]^

path = "github.com/google/docsy/dependencies")>>config.toml
hugo server

You now can preview your new site inside your browser at http://localhost:1313.

Detailed Setup instructions

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 Docs theme as a submodule, 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, `config.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. You must also declare the submodule dependencies as a second dependency. This submodule pulls in both a workaround for a bug in Go’s module management and the dependencies bootstrap and Font-Awesome.

hugo mod get github.com/google/docsy@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre

These commands add both the docsy theme module and the dependencies submodule to your definition file go.mod.

Add theme module configuration settings

Add the settings in the following snippet at the end of your site configuration file (default: config.toml) and save the file.

• config.toml
• config.yaml
• config.json

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

module:
  hugoVersion:
    extended: true
    min: 0.73.0
  imports:
    - path: github.com/google/docsy
      disable: false
  imports:
    - path: github.com/google/docsy/dependencies
      disable: false

{
  "module": {
    "hugoVersion": {
      "extended": true,
      "min": "0.73.0"
    },
    "imports": [
      {
        "path": "github.com/google/docsy",
        "disable": false
      },
      {
        "path": "github.com/google/docsy/dependencies",
        "disable": false
      }
    ]
  }
}

Preview your site

To build and preview your site locally:

hugo server

By default, your site will be available at http://localhost:1313. When encountering problems, have a look at the known issues on MacOS.

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.

What’s next?

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

2 - Other setup options

If you don’t want to use Docsy as a Hugo Module (for example if you do not want to install Go) but still don’t want to copy the theme files into your own repo, you can use Docsy as a Git submodule. Using submodules also lets Hugo use the theme files from Docsy repo, though is more complicated to maintain than the Hugo Modules approach. This is the approach used in older versions of the Docsy example site, and is still supported. If you are using Docsy as a submodule but would like to migrate to Hugo Modules, see our migration guide.

Alternatively if you don’t want Hugo to have to get the theme files from an external repo (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 files directly into your site source.

This guide provides instructions for both these options, along with common prerequisites.

Prerequisites and installation

Install Hugo

You need a recent extended version (we recommend version 0.73.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

Be careful using sudo apt-get install hugo, as it doesn’t get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

If you’ve already installed Hugo, check your version:

hugo version

If the result is v0.73 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:

1. Go to the Hugo releases page.

2. In the most recent release, scroll down until you find a list of Extended versions.

3. Download the latest extended version (hugo_extended_0.9X_Linux-64bit.tar.gz).

4. Create a new directory:

   mkdir hugo
   

5. Extract the files you downloaded to hugo.

6. Switch to your new directory:

   cd hugo
   

7. Install Hugo:

   sudo install hugo /usr/bin    
   

On macOS

Install Hugo using Brew.

As an npm module

You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:

npm install hugo-extended --save-dev

See the hugo-bin documentation for usage details.

Install PostCSS

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:

npm install -D autoprefixer
npm install -D postcss-cli

Starting in version 8 of postcss-cli, you must also separately install postcss:

npm install -D postcss

Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.

Other option 1: Use the theme as a submodule

To create a new Hugo site project and then add the Docsy theme as a submodule, run the following commands from your project’s root directory.

hugo new site myproject
cd myproject
git init
git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive

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

git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive

Other option 2: Clone the Docsy theme

If you don’t want to use a 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 into your project’s theme folder, run the following commands from your project’s root directory:

cd themes
git clone https://github.com/google/docsy

If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:

git submodule update --init --recursive

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

Preview your site

To build and preview your site locally:

cd myproject
hugo server

By default, your site will be available at http://localhost:1313/. See the known issues on MacOS.

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.

What’s next?

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

3 - Deploy Docsy inside a Docker container

We provide a Docker image that you can use to run and test your Docsy site locally, without having to install all Docsy’s dependencies.

Install the prerequisites

1. On Mac and Windows, download and install Docker Desktop. On Linux, install Docker engine and Docker compose.

   The installation may require you to reboot your computer for the changes to take effect.

2. Install git.

Create your repository from the docsy-example template

The docsy-example repository provides a basic site structure that you can use as starting point to create your own documentation.

1. Use the docsy-example template to create your own repository.

2. Download the code to your local machine by cloning your newly created repository.

3. Change your working directory to the newly created folder:

   cd docsy-example
   

Build and run the container

The docsy-example repository includes a Dockerfile that you can use to run your site.

1. Build the docker image:

   docker-compose build
   

2. Run the built image:

   docker-compose up
   

3. Open the address http://localhost:1313 in your web browser to load the docsy-example homepage. You can now make changes to the source files, those changes will be live-reloaded in your browser.

Cleanup

To cleanup your system and delete the container image follow the next steps.

1. Stop Docker Compose with Ctrl + C.

2. Remove the produced images

   docker-compose rm
   

What’s next?

• Learn about basic setup and configurations for Docsy.
• Add content and customize your site
• Publish your site.

4 - Basic site configuration

Site-wide configuration details and parameters are defined in your project’s config.toml file. 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 config.toml in the example project for how to add this information. We recommend copying this config.toml 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 config.toml file straight away:

Internationalization

The copied config.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 config.toml:

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

[languages.fa]
title = "اسناد گلدی"
description = "یک نمونه برای پوسته داکسی"
languageName ="فارسی"
contentDir = "content/fa"
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 = "011737558837375720776:fsdu1nryfng"

To use your own Custom Search Engine, replace the value in the gcs_engine_id with the ID of your own search engine. Or choose another search option.

What’s next?

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

5 - Known issues

The following issues are know 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 set 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.