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 of Hugo, version 0.160.1 or later. For installation options, including the npm-managed hugo-extended package, see Install Hugo.

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: run npm run install:safe from your site root; in an older copy without that script, use your repository’s own install script.
Sites using Docsy as an NPM package: install from your site root, for example with npm install.
Hugo module sites built from scratch: see Install npm dependencies.
Sites using Docsy as a Git submodule or a cloned theme: run npm run install:theme-deps from themes/docsy.

Missing Dart Sass compiler

If Hugo can’t find the Dart Sass sass CLI on its PATH, it fails while compiling SCSS with an error like: