hugo-clarity: a Hugo theme built on VMware's Clarity design system

A design system borrowed, not reinvented

hugo-clarity is a theme for Hugo based on VMware's open source Clarity design system, and the README positions it as a technology-minded theme for a personal site. A live demo is published at neonmirrors.net, and the repository carries screenshots for desktop and mobile in both light and dark mode.

The choice of Clarity is the interesting part of the design. Clarity is a design system with an existing component vocabulary, type scale and colour behaviour, and building a Hugo theme on it means the typography, spacing and control styling come from a system that other products already use, rather than from a designer inventing a look for one site. The result reads as an enterprise design language applied to a blog, which is either exactly what you want or exactly what you do not.

What the theme is not is minimal. The feature list covers a blog with tagging and category options, search, deeplinks, a choice of whether to use Hugo page bundles, native image lazy loading, dark mode with user preference controls in the UI, a toggleable table of contents, toggleable automatic figure numbering, a configurable site disclaimer, flexible image configuration with WebP support, logo alignment, mobile support with configurable menu alignment, and syntax highlighting.

The primary language of the repository is HTML, which is what a Hugo theme is, and the layout follows the conventions the static site generator expects: layouts/ for templates, assets/ for the styles and scripts, static/ for files copied verbatim, i18n/ for translations, resources/ for generated assets, archetypes/ for content scaffolding, an exampleSite/ for local development, and a theme.toml for the theme metadata.

Code blocks are the feature the theme is built around

The README's most detailed feature is the code block, and the way it is written tells you what kind of reader this theme is for.

Beyond syntax highlighting, the code block functions are copy to clipboard, a toggle for line wrap that is described as dynamic, a toggle for line numbers, a language label, and a toggle for block expansion and contraction that is also dynamic. A preview animation in the README shows all of them together.

The two dynamic ones are the details worth noticing. A dynamic line wrap toggle means the block rewraps when the viewport changes rather than scrolling horizontally, and a dynamic expansion toggle means a long block can be collapsed and opened without losing the reader's place. Those are the two behaviours that separate a blog theme that renders code from one that was designed around code, and for a technology blog the second one is the difference between a post that is readable and a post that is a wall.

Everything else in the feature list, the tagging, the search, the deeplinks, the image handling, the disclaimers, the pinned featured posts, the notices, the custom CSS and JavaScript hooks, the open street map integration, the comments, the math notation, the internationalisation and the table of contents, is standard scope for a serious Hugo theme. The code block is the one that goes past standard.

It is also the part most likely to need the most theme-specific CSS, which is worth keeping in mind when you customise.

The extended build of Hugo is a hard requirement

The prerequisites section is short and pointed. You need the extended version of Hugo 0.91.0 or above, and the README adds a warning that software repositories may be several versions behind and may not include the extended version at all.

That requirement is not arbitrary. The extended build is the one that carries the extra image processing backends, and this theme's image features are extensive: native lazy loading, flexible image configuration, support for modern formats such as WebP, image captions, figure positions added to captions, inline images, images floated to the left, round borders, and CSS classes you can add to images yourself. Plus the featured image, the thumbnail image and the share image, and logo alignment. None of that works with the plain build.

The practical consequence for someone installing the theme is that the version check happens early and the failure mode is a confusing one if you skip it, because the site builds and the images do not process. So the first step is to confirm the extended version is what is on your path, not to start pulling the theme.

Two more details from the same section are worth carrying into a project plan. The README links to Hugo's own installation instructions rather than restating them, which is the right place to look for per platform guidance. And the note about repositories lagging is a real one on older distributions, where the packaged Hugo can be several minor versions behind and the extended variant may be missing entirely.

Three ways to run it, and one that is only for theme work

The README gives three ways to use the theme, and they serve different purposes.

The first is Gitpod. The button in the README opens a prebuilt environment with a site ready to go, and the README describes it as the easiest option for trying out the theme, for quick experimentation, and for contributing pull requests. There is a link to a general overview of using Gitpod to create a pull request, which tells you this is a workflow choice as much as a tool choice.

The second is local development, using the example site in the repository.

git clone https://github.com/chipzoller/hugo-clarity
cd hugo-clarity/exampleSite/
hugo server --themesDir ../..

The themesDir flag points Hugo at the parent directory so the example site resolves the theme from the checkout rather than from a release. The README immediately warns that this is a good way to work on the theme but not a good way to work on your own site, because it uses the content from exampleSite and would not be aware of any overrides your site might apply to the theme. That warning is the kind of detail that saves an afternoon.

The third is Hugo modules, and the README calls it the option that arguably requires the least effort to run and maintain a site with this theme. It assumes you have already run hugo new site for your site and are in that directory, and it needs the go binary installed, with a note for Mac users to install go with brew.

hugo mod init <sitename>

The module route is the one for a real deployment, because the theme version then follows the module system rather than a copy in your repository.

A configuration surface larger than most themes

The table of contents of the README is a better description of the theme's real shape than the feature list, because it is the configuration surface a user actually maintains.

At the top level there are global parameters and page parameters. Menus are covered separately, with a main menu and social media entries, and there is a section on the search engine, on the blog directory, on mobile menu positioning, on tags and taxonomies, and on images.

The image section is the longest. It covers organising page resources, support for modern formats, image captions, adding figure positions to those captions, inline images, floating images to the left, round borders for images, adding CSS classes to images, the featured image, the thumbnail image, the share image, and logo alignment. That is a dozen separate decisions, each of which is a parameter somewhere in your site configuration.

Then the rest: code, the table of contents, pinning featured posts, notices, custom CSS and JavaScript, a custom site disclaimer, forcing light or dark mode, internationalisation, hooks, comments, math notation, an open street map section, and search.

Two of those deserve a note. The site disclaimer is described as configurable, with the example given being a statement that your views are not your employer's, which tells you the intended audience: people who write professionally on the side. And the hooks section means the theme exposes extension points, which is what a theme that is not a rigid template should do, and which is also what makes the theme survive a Hugo upgrade differently from a theme that hardcodes everything.

Hooks, translations and a licence you must read

Two things in the repository deserve attention before you build a site on it.

The first is the licence. The project is recorded as having a custom licence that GitHub cannot classify, with a pointer to the LICENSE file, which here is LICENSE.md at the top of the repository. That is not a red flag on its own, but it does mean the terms are in a file you have to read and interpret yourself, and that no automated tooling will tell you whether the use you have in mind is permitted. For a theme that is mostly presentation markup, that is usually fine. For a company that wants to fork it, read it first.

The second is the shape of the repository, which shows a theme that is maintained as a real project rather than a one-off template. There is a.gitpod.yml for the browser development environment, a.github directory for the workflows, a.vscode directory for editor settings, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md that the README points to from both development routes, an i18n directory for translations, and a theme.toml file carrying the theme metadata Hugo reads.

The archetypes directory is worth understanding, since it is the part most theme users never look at. Archetypes are the content templates Hugo uses when you create a new post, so this directory decides what a new article starts as, which front matter fields it has and which layout it picks. If the theme offers a featured image or a taxonomy by default, that behaviour usually starts here rather than in a template.

The maintenance picture is thin on the outside. There are no GitHub releases for the project, and the last push was on 2026-09-02, with the repository not archived. So you consume the master branch, and the version you get is the version that was on master that day.

Where a feature-complete theme is the wrong choice

The case against hugo-clarity is not quality, it is surface area, and it is worth naming before you install it.

A theme with a dozen image options, menus, search, comments, math notation, maps, notices, disclaimers, hooks and internationalisation is a theme you configure rather than install. Every one of those options is a parameter in your site configuration that you have to understand, and every one of them is a thing that can interact with the others, for example a featured image size that conflicts with the share image crop, or a mobile menu setting that interacts with the logo alignment.

The alternative is a minimal Hugo theme. The difference in approach is straightforward: a minimal theme gives you a small set of templates and leaves everything else to you, so your content and your own CSS decide the result, and there is a much smaller amount of configuration to keep correct across upgrades. The trade is that you write the parts hugo-clarity has already written, and you accept that a feature like the code block toolbar will not exist unless you build it.

For a technical blog where the code block is the centre of the reading experience, the argument for a purpose-built theme is straightforward. For a site with a handful of posts and a simple structure, a minimal theme is less work.

One operational point deserves the last word. Because there are no tagged releases, the theme you install from master can change under you, and a Hugo theme is templates and assets that a Hugo upgrade can also invalidate. So the sensible starting point is to run the example site locally with the themesDir flag, read the configuration reference for the features you actually want, and pin what you take from the theme by copying the templates you rely on into your own site rather than depending on them in place.

Editorial conclusion

hugo-clarity fits a technical blog where the code block is the centre of the reading experience and the author wants menus, search, tagging and image handling already solved, and it does not fit a simple site that would rather configure a minimal theme. Before adopting it, read the LICENSE.md file, since the terms are custom and GitHub cannot classify them, confirm you have the extended build of Hugo 0.91 or newer, and run the exampleSite locally with the themesDir flag before moving it into a Hugo module.

Frequently asked questions

Official sources

1. chipzoller/hugo-clarity on GitHub
2. Issues
3. README