docsy-example is a working Docsy site, and the safest way to start your own

A theme module, pulled in rather than vendored

Docsy is a Hugo theme module for technical documentation sites, providing easy site navigation, structure and more. The Docsy Example Project pulls in the Docsy theme as a Hugo module, together with its dependencies, and provides a skeleton documentation structure for you to use.

The mechanism matters more than it first appears. A Hugo module is resolved by the Hugo module system, which means the theme is a declared dependency with a version rather than a directory of files copied into the tree. The go.mod in the repository shows it plainly.

module github.com/docsy/docsy-example

go 1.12

require github.com/docsy/docsy/theme v0.18.0 // indirect

The docsy.work and docsy.work.sum files are the Hugo module workspace and its checksum record, and the version in go.mod tracks the theme release rather than the site version. The package version in package.json is a dev build, 0.18.1-dev with a commit hash and a branch suffix, which tells you the site content itself is versioned separately from the theme it renders.

So the repository is two things at once, an example site that is deployed on Netlify at example.docsy.dev, and a starting point you can copy. The documentation is explicit that it is not an officially supported Google product, and that the project is currently maintained.

Running it locally needs npm, not a direct hugo call

The local development instructions are the part of this repository that most people will hit a snag on, and the reason is specific.

The prerequisites are Node.js and npm, with minimum versions enforced at install time, plus Go and Git. Hugo itself comes from the pinned hugo-extended npm package, so you do not install Hugo separately. On Windows the npm scripts run under Bash, which ships with Git for Windows, so you need `bash` on your PATH.

The install step is one script.

npm run install:safe

This performs a clean, script-free install of the pinned dependencies, and the Hugo binary self-installs at first use. For dependency management, that is the lockfile, the generated theme manifest and Hugo updates, the maintainer notes are the place to look.

Then the preview server.

npm run serve

And the reason for all of this is stated at the end of the section: run Hugo through the npm scripts, as above, they put the Dart Sass `sass` CLI from `node_modules` on the `PATH`, and a direct `hugo` invocation fails without it.

That is a genuine trap. A team that has Hugo installed system wide and runs it directly will hit a Sass error and conclude the theme is broken, when the issue is that the Sass implementation the theme expects is a Node package.

The npm scripts show how the site is actually built

The package.json is the clearest description of the build, and it is worth reading in full because it shows how the theme version, the Hugo binary and the site content relate.

The internal scripts carry a leading underscore, and the public ones call them. The Hugo invocation is always through a wrapper, _hugo is `hugo --cleanDestinationDir`, and the dev variant adds the dev environment and the -DFE flag.

    "_hugo-dev": "npm run _hugo -- -e dev --logLevel info -DFE",
    "_hugo": "hugo --cleanDestinationDir",
    "_local": "cross-env HUGO_MODULE_WORKSPACE=docsy.work",
    "_serve": "npm run _hugo-dev -- --minify serve --renderToMemory",
    "_get:docsy": "hugo mod get github.com/docsy/docsy/theme@v$npm_package_version",

Two details carry the weight. The _get:docsy script uses $npm_package_version, so the theme version fetched is taken from the package.json version rather than being written out again, which is what keeps the go.mod requirement and the site in step. And the _local script sets HUGO_MODULE_WORKSPACE to docsy.work, so the local build resolves the theme from the workspace file instead of the network, which is what makes an offline or reproducible build possible.

There is also an approve:hugo script, which runs the safe install and then npm approve-scripts with the --allow-scripts-pin flag for hugo-extended, because npm blocks install scripts by default and the Hugo binary installs itself on first use. That single flag is the difference between a working local build and a silent failure.

The content skeleton is the part you actually inherit

The repository layout shows what a Docsy site carries, and the directories with content in them are the ones that define the shape of your documentation.

There is a content/ directory holding the Markdown pages, a config.yaml and a hugo.yaml for the site and module configuration, a layouts/ directory, a static/ directory for assets, and assets/ for the source assets the theme compiles. There is a packages/ directory with a single workspace member, packages/hugoautogen, and a tasks/ directory.

The content structure is what you keep when you use this as a template, and the user guide is explicit that the right way to start is to follow the template guide, which walks through cloning or templating this repo and previewing the result.

The other directories are the machinery. A tests/ directory and a tasks/ directory, plus a link-cache.jsonc and a lychee.toml, which together are the link checking setup, and the _check:links script calls lychee-norm-cache. There is a .cspell.yml for the spell checker, and a comment at the bottom of the README noting that cSpell should ignore hugo and docsy.

Renovate is configured as well, through renovate.jsonc, and prettier handles formatting with a .prettierignore, so the site is linted, spell checked, link checked and dependency updated by the same repository that holds the content.

Deployment is Netlify, and the build is scripted rather than configured in the UI

The site is hosted on Netlify at example.docsy.dev, and the netlify.toml file in the repository holds that configuration.

The package.json shows the deployment path as a script rather than a settings page, and that is the interesting part. The _commit:public script hashes the current main branch and commits the built site into a public directory with an empty commit.

    "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit --allow-empty -m \"Site at $HASH\"",

The _netlify:prepare script runs the clean check, the safe install and the clean check again, so a deployment always starts from a known state.

The build scripts are separated by purpose. build:production runs Hugo with the minify flag for a real build, and build:preview adds a baseURL taken from DEPLOY_PRIME_URL or a fallback of /. The build script wraps the underscore build with a baseURL from BASE_URL or http://localhost, and cross-env is used to set that variable so the same script works on Windows.

For a documentation site, a scripted deployment is a reasonable choice, since the site has to be rebuilt on every content change and the build environment is the same in CI and on a laptop. The cost is that the deployment is defined in two places, the netlify.toml and the npm scripts, and a team changing one has to know about the other.

Where this example site is the wrong thing to copy

There are reasons to look past this repository, and the honest one is that it is a site with content, not a theme to install.

If you want Docsy in a site you already have, the right integration is the Hugo module in your own go.mod, and pulling this repository is a heavier step than that. The example carries content, assets, tests and a Netlify deployment arrangement, none of which you necessarily want in a project whose documentation lives somewhere else.

The second limit is the toolchain coupling. The site assumes Node.js with npm, because Hugo arrives as a pinned npm package and because the Dart Sass CLI has to be on the PATH. A team with a Go-only or container-only build has to accommodate that, and the README's own guidance for Windows is that the npm scripts run under Bash from Git for Windows, which is a sign of how much of the surrounding setup the scripts assume.

The third is that the theme version and the site version move separately. The theme is pinned in go.mod at v0.18.0, the site is a dev version, and the _update:docsy:post script runs hugo mod tidy before repacking. That is a workable arrangement, but it means updating the theme is a deliberate operation with its own scripts, not a dependency bump.

The alternative is to start from the Docsy theme module directly and write the content structure yourself, using this example as a reference for the configuration and the module setup rather than as a base to fork. The example is most useful as a known-good configuration to copy from, and least useful as a codebase to inherit.

Editorial conclusion

docsy-example fits a team that wants a working Hugo and Docsy site before writing any content, since the repository already resolves the theme module, the Dart Sass requirement and the content skeleton that most first attempts get wrong. It does not fit a team that wants a theme to install rather than a project to copy, and it does not fit a build pipeline that does not use npm. Before starting from it, follow the template guide in the Docsy user guide rather than copying the tree by hand, keep the pinned hugo-extended package and the docsy.work workspace in step, and read the maintainer notes in CONTRIBUTING.md, which is where the lockfile, the generated theme manifest and the Hugo update process are documented.

Frequently asked questions

Official sources

1. docsy/docsy-example on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases