Get started on Docsy

Other setup options

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

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:

Prerequisites

Install Hugo

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

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: