DocuAPI: a multilingual API documentation theme for Hugo

A documentation theme built on a documentation theme

DocuAPI is described as a beautiful multilingual API documentation theme for Hugo, and the interesting part of its pedigree is in the second sentence of the README.

The theme is built on top of the work of Robert Lord and others on the Slate project, which is itself an API documentation design. Slate is the reference implementation of the three column documentation layout, and a theme that inherits its design language inherits a set of decisions that took a lot of iteration to settle: how the sidebar behaves, how a method and its parameters are laid out, how code samples are presented.

That lineage is worth understanding because it is the reason the theme exists at all. Hugo is a static site generator, and it has no built in idea of what an API reference looks like. A theme provides that, and DocuAPI provides it with Slate's design already settled rather than reinventing it.

The other change the README calls out is more recent and more consequential for anyone extending the theme. The JavaScript part has been rewritten from jQuery to AlpineJS, the small declarative library that ships the JavaScript libraries as Hugo modules.

So there is a fork in the road inside the project itself. The old version is still there and still installable, and the new one is the version you get from the current module path.

Importing the theme, and the two versions

Using the theme means importing it in your Hugo configuration as a module.

[[module.imports]]
path = "github.com/bep/docuapi/v2"

The path is the whole instruction, and the version suffix is the whole choice.

The README notes that if you want the older jQuery version, you replace the path with the module path without the version suffix. That single line is the difference between the two implementations of the theme, and it means the choice is per project rather than per site, which is a reasonable thing for a theme to support.

If you want to edit the SCSS styles, the README lists two requirements: the extended version of Hugo, and the PostCSS command line tool, with the note to run npm install to install the requirements.

The extended Hugo requirement is not a formality. Hugo modules, which is the mechanism the import above uses, are a feature of the extended build. The PostCSS requirement is there because the styles are compiled with PostCSS and Autoprefixer, which means the theme's own styles are built by a JavaScript toolchain rather than by Hugo's built in SCSS pipeline alone.

The theme documentation points at the example site directory for the available options, and specifically at its Hugo configuration file, which is where the settings for the theme live.

The central assumption: one page of documentation

The README flags this as the most notable behaviour, and it is the thing to understand before you install the theme.

This theme will use all the non draft pages in the site and build a single page of API documentation.

So the theme is not a component library that you place on individual pages. It takes the pages you already have, in front matter order, and renders them as one continuous document with a sidebar, which is the Slate model.

The ordering is controlled by weight in the page front matter, and the README says that using weight is the easiest way to control page order. If you want a different selection of pages, you provide your own layouts/index.html template.

That last sentence is the escape hatch and it is a significant one, because it tells you the theme is not a closed box. Replacing the index template means you can define which pages appear and in what structure, and you can still use the rest of the theme, including its partials and its styles.

For a documentation site this is the right default, since an API reference is normally a single navigable document. For a documentation site that also has guides, tutorials and blog posts, the weight mechanism and the custom template are how you reconcile the two.

Customising the look through CSS variables and hooks

There are two extension points, and they sit at different levels.

The first is the visual one. You customise the look and feel by adding your own CSS variables in the overrides stylesheet inside the assets styles directory, and the README points at the example site for an example of how.

The second is the structural one, the hooks. You override the layouts by providing custom partials, and the README names each one and its insertion point.

There is a hook inserted right before the head end tag, which the README says is useful for additional styles. There is one for the end of the body. There is one at the start of the left sidebar and one at its end, and one that provides the source of the logo image in the sidebar.

The hooks for the styles and the JavaScript imports are treated separately, and the README notes that both the styles and the JavaScript import are put in each partial and can be overridden if really needed. That phrasing is a warning as much as an invitation, since overriding the JavaScript import means taking responsibility for what the theme's behaviour depends on.

The five named hooks cover the cases that come up in practice, which is a sensible amount of surface area. Most customisation is a logo, a colour and an extra stylesheet, and all three are covered without touching the theme's templates.

Translations, search and the underlying libraries

Multilingual support is in the description, and the repository layout shows how it is done. There is an internationalisation directory in the theme, which is the standard Hugo arrangement, with the strings for each language alongside the templates.

Search comes from a JavaScript library, and the module file shows which one. The theme depends on the lunr.js search library and on a distribution of the AlpineJS libraries packaged for Hugo modules, and on the Slate project itself, which is where the theme inherits the documentation design.

That module file is a small and revealing document. The module path carries the major version, and the Go version requirement is 1.16, which tells you that the theme is built with a Hugo module toolchain rather than with the older vendored theme mechanism. The dependencies are all marked as indirect, since they are consumed by the templates rather than called from Go code.

The AlpineJS dependency is the modern part of the story. Shipping the browser libraries as Hugo modules means they are fetched, pinned and served by Hugo itself, so the theme does not carry a bundled copy of a JavaScript library that would need patching when the library is updated. That is a meaningful improvement over the jQuery era, where a vendored script was a maintenance liability.

Repository, releases and what to check

The repository is a Hugo theme with the usual parts. There is a layouts directory with the templates, an assets directory with the styles and scripts, a static directory with the files served as they are, an internationalisation directory with the translations, an archetypes directory for scaffolding new content, and an example site directory that doubles as the documentation. There is also a theme configuration file, a site configuration file, a Netlify configuration for the demo deployment, and a Go module definition.

The JavaScript side is small. The package manifest lists PostCSS with its command line tool and Autoprefixer as the development dependencies, and the engines field asks for Node 8.9 or later and npm 6 or later. That is an old baseline, which tells you the styles build has not needed modern Node for a while.

The release tags are v2.5.1 from 2026-08-29, v2.5.0 from 2026-03-01 and v2.4.2 from 2025-04-17, and the last push was on 2026-10-13. The package manifest still carries the version 1.4.0, which is a leftover from before the theme moved to the versioned module path and is one of those inconsistencies that costs a reader a minute.

Three checks before you adopt it. Whether the single page model fits your documentation, because if it does not you will be writing your own index template. Whether the theme's design is what you want, since Slate is a specific look and inheriting it means inheriting its opinions about density and colour. And whether you need the older jQuery version for a reason, because if you do, the older module path is a maintained fork rather than the same thing.

Editorial conclusion

DocuAPI suits a team with an API written up as Markdown pages in a Hugo site who want a documentation site that looks designed rather than generated, since the theme supplies the navigation, search and translation handling that you would otherwise build. It is the wrong choice if your API documentation is generated from an OpenAPI definition, because the theme consumes pages rather than a schema, and the wrong choice if you need a specific layout, since the single page structure is the theme's central assumption. Verify first that the theme's page selection matches how your pages are organised, that the Hugo extended version and PostCSS are available if you intend to edit the styles, and which of the two module paths you need, since the older path gives you the jQuery version.

Frequently asked questions

Official sources

1. bep/docuapi on GitHub
2. Issues
3. Project website
4. README
5. Releases