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.

Troubleshooting and known issues

Mon, 01 Jan 0001 00:00:00 +0000

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, and sites using Docsy as an NPM package: run npm install from your site root.
Hugo module sites built from scratch: see Install theme npm dependencies.
Sites using Docsy as a Git submodule or a cloned theme: run npm run postinstall from themes/docsy.

Known issues

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