Use Docsy as a Hugo Module on Docsy

Before you begin

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

Note

The example site’s pinned npm dependencies provide Hugo and Dart Sass, so if that’s your starting point, skip those sections: install only Go, Git, and Node.js. On Windows, also ensure that Bash is on your PATH: the example site’s npm scripts run under Bash, which ships with Git for Windows.

Install Hugo

You need a recent extended version of Hugo, version 0.160.1 or later, to build and preview sites that use Docsy. Check your version, and ensure that the output mentions extended:

Create a new site: start with a prepopulated site

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

The Docsy example site gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary.

If you prefer to create a site from scratch, follow Start a site from scratch.

TL;DR: Setup for the impatient expert

With the prerequisites installed (on Windows, including Bash on your PATH), run:

git clone --depth 1 --branch v0.17.0 https://github.com/docsy/docsy-example.git my-new-site
cd my-new-site
npm run install:safe
npm run serve

Preview at http://localhost:1313/. If the build fails, see Troubleshooting.

Create a new site: start a new site from scratch

Wed, 08 Dec 2021 09:21:54 +0100

Creating a site from scratch gives you Docsy’s look and feel, navigation, and other features, but you specify your own site structure. These instructions give you a minimum file structure only, so that you build and extend your actual site step by step.

TL;DR: Setup for the impatient expert

Run:

hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/docsy/docsy/theme@v0.17.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/docsy/docsy/theme"
EOL
npm install --save-exact --save-dev sass-embedded@1.105.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server

hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/docsy/docsy/theme@v0.17.0
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/docsy/docsy/theme") >> hugo.toml
npm install --save-exact --save-dev sass-embedded@1.105.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server

Preview at http://localhost:1313/.