# Docsy: a Hugo theme for documentation sites, and what it costs to adopt

> Docsy is a Hugo theme for technical documentation sets, distributed as a Hugo module, an npm package, a Git submodule or a clone. It needs the Hugo extended build, Dart Sass and PostCSS, and it is opinionated about how a docs site is structured.

**docsy/docsy** — Hugo theme for open source documentation

- Repository: https://github.com/docsy/docsy
- Website: https://docsy.dev
- Stars: 2,966 · Forks: 981
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/docsy-docsy

## What Docsy solves, and which documentation teams it fits

Docsy is a Hugo theme aimed at technical documentation sets. The README describes it as providing "simple navigation, site structure, and more", which is a fair summary of what a docs theme actually has to do: give a large body of pages a sidebar, a table of contents, versioned navigation, and a build that stays fast as the page count grows. Hugo supplies the static site generator; Docsy supplies the layouts, the navigation model and the shortcodes on top of it.

The audience is narrow and specific. You need to be on Hugo already, or willing to move to it. You need a site with enough pages that hand-written navigation becomes a maintenance problem. You need contributors who write Markdown rather than HTML. If your documentation is five pages and one author, a theme of this size is overhead you will feel every time you upgrade Hugo.

One thing worth reading before anything else: the README carries a warning that the main branch is under development and not officially supported, and directs users to official releases. That is unusual honesty for a theme README, and it tells you the project expects people to pin versions rather than track the branch.

## How the theme is put together: modules, workspaces and a patched Bootstrap

The repository root is not the theme. The theme lives in theme/, and the root package.json declares npm workspaces for docsy.dev and theme. docsy.dev is the documentation site for the project itself, built with Docsy, which means the theme's own docs are a live test of the theme.

The published npm package is @docsy/theme, and the files list in package.json shows what ships: the theme directory, minus its own LICENSE, minus theme/images, minus node_modules, and minus the script test files. So the package you install is the theme assets and layouts, not the project's build tooling.

The interesting part is the Bootstrap handling. Several npm scripts exist purely to patch it: _cp:bs-scrollspy runs a Perl script to extract a method, _prepare:scrollspy-patch applies a patch and then updates the patch JavaScript, and _prepare chains those together. Docsy does not vendor Bootstrap wholesale; it carries a patch against it for scrollspy behaviour. That is a real design decision with a real cost, because a Bootstrap upgrade means re-applying the patch, and the scripts are written in Perl and Bash rather than Node.

Styling goes through Hugo's asset pipeline with Dart Sass and PostCSS. The README is explicit that Hugo looks up the Sass compiler as the sass CLI on its PATH, and that PostCSS is needed so the site build can create the final CSS assets. Neither of those is bundled for you.

## Installing Docsy and building a first site

The README gives two routes. The recommended one is to start from the Docsy Example Project, which already includes the theme as a Hugo module, and customize it into your own site. The other is to add Docsy to an existing Hugo site, as an npm package, a Hugo module, a Git submodule, or a clone.

Before either, the prerequisites have to be in place. Hugo must be the extended release, Dart Sass must be on your PATH as sass, and PostCSS has to be installed in the project. The README gives these commands from the root of your project:

```bash
npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
```

It then adds a note that from version 8 of postcss-cli onward you must install postcss separately as well:

```bash
npm install -D postcss
```

If you choose the Hugo module route, which the README recommends, you also need Go installed alongside Hugo and PostCSS. That is the trade the module route makes: cleaner upgrades, one more toolchain on the build machine.

To run the theme's own documentation locally, the README gives a short sequence. Clone the repository shallowly, enter it, install safely, then serve:

```bash
npm run install:safe
npm run serve
```

The install:safe script is not a plain npm install. The package.json shows it split into _install:safe:pre, which runs npm ci with --ignore-scripts --no-audit --no-fund, and _install:safe:post, which rebuilds Hugo extended and then installs the theme dependencies. So the safe path deliberately skips lifecycle scripts on the first pass and rebuilds Hugo itself afterward. Expect that step to take a while the first time.

One platform detail the README calls out: npm scripts in this repository run under Bash on every platform because of a script-shell pin in .npmrc, so on Windows you need Git Bash's bash on your PATH. If you are on Windows and your build fails immediately with a shell error, that is the cause.

## Where Docsy gets in the way

The prerequisite list is the first real cost. Hugo extended, Dart Sass and PostCSS all have to exist on every machine that builds the site, including CI. That is three toolchains to keep in step, and the failure mode when one drifts is a build error rather than a degraded page. A theme that compiles Sass at build time cannot fall back gracefully.

The second cost is the Bootstrap patch. The scrollspy patch means Docsy's relationship to Bootstrap is not a version range in package.json but a set of scripts that transform Bootstrap's source. Upgrading Bootstrap is therefore a maintenance task for the theme maintainers, not something you can do on your own schedule, and if you fork Docsy you inherit that task.

The third is the branch policy. The README states plainly that main is under development and not officially supported, and points to releases instead. If your workflow is to track a theme's default branch, you are working outside the support the project offers. Pin a release.

Finally, consider when Docsy is simply the wrong tool. If your content is not documentation, the navigation model and shortcodes will fight you. If you want a single binary build with no Node in the loop, Hugo alone with a hand-written layout is less machinery. And if your site is small enough that a sidebar is one hand-edited list, the theme adds more surface than it removes.

## Docsy compared with plain Hugo layouts

The honest alternative is not another documentation theme; it is Hugo's own layout system. Hugo gives you content organization, taxonomies, menus, partials and shortcodes, and a build that needs no Node at all. Everything Docsy adds sits on top of that: prebuilt layouts for documentation sections, a navigation and sidebar model, and a set of shortcodes for the things docs pages need.

The difference in approach is where the complexity lives. With plain Hugo, you write the layouts and you own the Sass pipeline, which can be as simple as Hugo's built-in asset handling with no PostCSS step. With Docsy, you adopt someone else's layouts and shortcodes and in exchange accept Dart Sass, PostCSS and npm on the build machine, plus the Bootstrap patch described above. Neither is wrong. They place the maintenance burden in different places: your repository, or the theme's release cycle.

If you are weighing this, the Docsy Example Project is the cheapest way to see which side you land on. It is a working site with the theme wired up as a module, so you can judge the layouts and shortcodes against your own content before committing to the prerequisite stack.

## Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived, and the last push to main was on 2026-09-21. Releases are frequent: v0.17.0 on 2026-08-30, v0.16.0 on 2026-07-29, v0.15.0 on 2026-05-01. The version in package.json is 0.17.1-dev, which is consistent with main running ahead of the last release. The README states that the project is actively being maintained, and the release cadence supports that.

The upgrade cost depends on which installation route you pick, and this is where the choice matters more than it looks. As a Hugo module, upgrades are a version bump and Hugo resolves the dependency. As an npm package, the theme arrives through npm and you manage it with the rest of your JavaScript dependencies. As a Git submodule or a clone, you are copying files into your project and upgrades become a manual merge, which is the route most likely to leave you stranded on an old version.

Licensing is Apache-2.0, stated in both the README and package.json. That is a permissive licence with an explicit patent grant, and it is the same licence Google uses for many of its open source projects. Note the README's disclaimer that this is not an officially supported Google product, which matters if you were assuming a support relationship. The repository also carries a technical charter, so governance is documented rather than implied. For the specifics of what Apache-2.0 requires of you in your own distribution, read the LICENSE file rather than taking a summary from anyone, including this article.

## Conclusion

Adopt Docsy if you already build with Hugo and want navigation, site structure and shortcodes without writing them yourself; the theme is Apache-2.0 and the last push to main was on 2026-09-21. Do not adopt it if you are not willing to run the extended Hugo binary plus Dart Sass and PostCSS on every build machine, or if you need a theme that tracks Hugo's newest features with no lag. Before committing, clone docsy-example, run npm run install:safe and npm run serve, and check that your own content renders under the theme's layout assumptions.

## FAQ

### What is Docsy?

Docsy is a Hugo theme for technical documentation sets. The README describes it as providing simple navigation, site structure and more, and it is distributed as a Hugo module, an npm package under @docsy/theme, a Git submodule, or a clone of the repository.

### How do I install Docsy?

Install the extended Hugo release, provide Dart Sass on your PATH as sass, and install PostCSS with autoprefixer and postcss-cli. Then either start from the Docsy Example Project or add the theme to an existing Hugo site as a module, npm package, submodule or clone.

### What is the best Hugo theme for documentation?

Docsy is built specifically for documentation sets, and the Docsy Example Project lets you evaluate its layouts and shortcodes against your own content before committing.

### Does Docsy work on Windows?

The README notes that npm scripts in the repository run under Bash on every platform because of a script-shell pin in .npmrc, so on Windows you need Git Bash's bash on your PATH. Beyond that, the prerequisites are the same as on other platforms.

### Can I use the main branch of Docsy?

The README warns that main is under development and not officially supported, and directs users to official Docsy releases instead. The package.json version is 0.17.1-dev, which is consistent with main running ahead of the last release.

## Sources

- [docsy/docsy on GitHub](https://github.com/docsy/docsy)
- [License: Apache-2.0](https://github.com/docsy/docsy/blob/main/LICENSE)
- [Project website](https://docsy.dev)
- [README](https://github.com/docsy/docsy/blob/main/README.md)
- [Releases](https://github.com/docsy/docsy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/docsy-docsy