Get started on Docsy

Other setup options

Wed, 08 Dec 2021 00:00:00 +0000

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

Deploy Docsy inside a Docker container

Mon, 30 Jul 2018 00:00:00 +0000

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

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

Create your repository from the docsy-example template

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

Basic site configuration

Wed, 08 Dec 2021 09:22:27 +0100

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.

Known issues

Wed, 08 Dec 2021 09:22:27 +0100

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: