This page helps you to setup and run a local Docsy site with Docker in 5 minutes.
Prerequisites and installation
Use our Docker image
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.
You can see how to get started with this approach by following our Docker Quickstart tutorial. If you don’t want to use Docker, follow the instructions below to install Hugo and PostCSS.
You need a recent extended version (we recommend version 0.75.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.
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:
If the result is
v0.75 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:
Go to the Hugo releases page.
In the most recent release, scroll down until you find a list of Extended versions.
Download the latest extended version (
Create a new directory:
Extract the files you downloaded to
Switch to your new directory:
sudo install hugo /usr/bin
Install Hugo using Brew.
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
hugo-bin documentation for usage details.
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
sudo npm install -D autoprefixer sudo npm install -D postcss-cli
Starting in version 8 of
postcss-cli, you must also separately install
sudo 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.
Using the theme
To use the Docsy Hugo theme, 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 Git submodule, so it’s easy to keep up to date.
- 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.
Option 1: Copy the Docsy example site
The Example Site gives you a good starting point for building your docs site and is pre-configured to use the Docsy theme as a Git submodule. You can copy the Example Site either by:
Using the GitHub UI
This is the simplest approach, as the Docsy example site repo is a template repository. To create your own copy of the Docsy example site repo:
Go to the repo page and click Use this template.
Type your chosen name for your new repository in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you now have a Docsy site repo!
To test your copied site locally with Hugo, or make local edits, you’ll also need to make a local copy of your new repository. To do this, use
git clone, replacing
https://github.com/my/example.gitwith your repo’s web URL (don’t forget to use
--recurse-submodulesor you won’t pull down some of the code you need to generate a working site):
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
You can now edit your local versions of the site’s source files. To preview your site, go to your site root directory and run
hugo server (see the known issues on MacOS). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use
Using the command line
To copy the example site:
Make a local working copy of the example site directly using
git clone https://github.com/google/docsy-example.git
Switch to the root of the cloned project, for example:
Get local copies of the project submodules so you can build and run your site locally:
git submodule update --init --recursive
Build your site:
Preview your site in your browser at: http://localhost:1313/. You can use
Ctrl + cto stop the Hugo server whenever you like. See the known issues on MacOS.
Now that you have a site running, you can push it to a new repository:
Create a new repository in GitHub for your site with your chosen repo name. For clarity you may also want to rename the root directory (
docsy-example) of your working copy to match, though everything will still work even if you don’t.
originin your project. From your site’s root directory, set the URL for
originto your new repo (otherwise you’ll be trying to push changes to
google/docsyrather than to your repo):
git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git
Verify that your remote is configured correctly by running:
git remote -v
Push your Docsy site to your repository:
git push -u origin master
Option 2: Use the Docsy theme in your own site
Specify the Docsy theme like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project’s
Whichever approach you use, for simplicity we recommend copying and editing our example site configuration for your project, or you may get Hugo errors for missing parameters and values when you try to build your site.
Using the Docsy theme as a submodule
Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in your repo that may result in merge conflicts when you try to update it. This is the approach used by our example 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 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
Cloning the Docsy theme to your project’s
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.
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
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.
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.
The Docsy example site comes with some defaults you may want to remove or customize straight away:
The Docsy example site supports 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
[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"
To remove the translated source files, delete both the
docsy-example/content/no and the
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.
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
To temporarily allow more open files:
View your current settings by running:
sudo launchctl limit maxfiles
Increase the limit to
65535files by running the following commands. If your site has fewer files, you can set choose to set lower soft (
65535) and hard (
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.
- Add content and customize your site
- Get some ideas from our Example Site and other Examples.
- Publish your site.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.