FixIt: a Hugo theme in the middle of a v1 rewrite, with an unusually broad feature list

Where the theme comes from, and the v1 warning you cannot ignore

FixIt is a clean, elegant but advanced blog theme for Hugo, and the lineage is stated plainly: it is based on the original LoveIt theme, the KeepIt theme and the LeaveIt theme. Three predecessors rather than one, which is a hint that this is an accumulated theme rather than a fresh design.

The repository is the hugo-fixit organisation's FixIt project, and the homepage is fixit.lruihao.cn, which hosts the documentation, a demo and a showcase of more examples. The primary language in the repository metadata is HTML, which is what a Hugo theme is made of, and the licence is MIT.

Then there is the warning at the top of the README, and it is the first thing any adopter needs to read. The main branch contains the v1 code. For upgrade instructions there is a v1 migration guide. And version 1.0.0 is planned for release in the first half of 2027, with an invitation to join the development and discussion.

That last date is the important one. A theme whose stable 1.0.0 is more than a year away is a theme where the main branch is the current product and the released versions are a moving beta line. The recent tags are v1.0.0-beta.4 on 2026-10-15, v1.0.0-beta.3 on 2026-10-12 and v1.0.0-beta.2 on 2026-10-09, so three beta tags in one week, and the package version in package.json is 1.0.0-beta.4. The last push was on 2026-10-15, the same day as the newest tag, and the repository is not archived.

So the practical question for anyone evaluating this is not whether the theme is good, it is whether you are willing to track a beta. The topics include hugo, hugo-theme, hugo-blog, hugo-fixit, pwa, pwa-app, algolia, giscus, content-encryption and fixit-encrypt, which describes a theme with a plugin ecosystem rather than a single template.

Getting a site started, and the four template flavours

The Quick Start page is the documented route to a new site, and the outline given is Installation, Getting Started, Content Management and Advanced Usage.

There is also a CLI tool for creating a project in one command:

pnpx fixit-cli create my-blog

That is a pnpm execution of a fixit-cli package, and the repository has an asciinema recording linked next to it, which is the kind of touch that makes a setup wizard usable by people who have not used it before.

Beyond the CLI there are four templates to generate a repository from, and the distinctions between them are worth reading before you pick one.

A quick-start template based on Hugo Modules uses the hugo-fixit-starter repository. A second quick-start template based on Git submodule uses hugo-fixit-starter1. A template for building multilingual sites uses the hugo-fixit/docs repository. And a template for customizing with the FixIt theme uses Lruihao/hugo-blog.

The Hugo Modules versus Git submodule split is the significant one, because it determines how the theme is consumed and therefore how you upgrade it. Hugo Modules pulls the theme through the module system, so version upgrades are a matter of changing a version string and running a module update. A Git submodule is a checkout inside your repository, so upgrading means pulling inside the submodule and committing the result. For a theme in beta with a v1 rewrite in progress, the difference in upgrade friction is not academic.

The multilingual template is listed separately from the others, which suggests multilingual support is treated as a first class scenario rather than a configuration option on top of the standard starter. That is consistent with the feature list, which includes multilanguage support and I18n readiness, and with the fact that the documentation site itself is available in English, Simplified Chinese, Traditional Chinese, French, Russian, Spanish, Hindi, German, Korean and Japanese.

That translation spread is itself a data point about the project's audience. A theme maintained with a documentation site in ten languages and a Gitee mirror of the repository is a theme with a large user base, and the Gitee star badge in the README header reflects that.

The feature list: comments, analytics, and offline support

The features section is long, and the two areas where it is longest are the ones that usually have to be reimplemented per site, which is where a theme earns its keep.

For comments, the theme supports Disqus, Gitalk, Valine, Waline, Facebook comments, Telegram comments and Utterances, and further down the same list there is a giscus.json file in the repository root, which is the configuration file for giscus, the GitHub Discussions based comment system that is in the topic tags. Choosing between a hosted service like Disqus, a self hosted one like Valine and Waline, a GitHub-native one like Gitalk and giscus, and a Telegram based one is a genuine decision with different trade-offs around moderation, privacy and data ownership, and shipping all of them means the theme does not force the choice.

For analytics, the list covers Google Analytics, Fathom Analytics, Baidu Analytics, Umami Analytics, Plausible Analytics and Cloudflare Web Analytics. Six services, and the mix is revealing. Google and Baidu are the ad-supported and China-market incumbents, Fathom and Umami are the privacy-respecting self-hostable options, Plausible is the commercial privacy option and Cloudflare Web Analytics is the free one that comes with a CDN you may already run. The theme also supports search engine verification for Google, Bing, Yandex, Pinterest, Baidu, 360 and Sogou, and a CDN option for third-party libraries, which matters for a site audience that includes users in China.

Other entries worth naming. Gravatar and a local avatar option, up to 86 social links and up to 25 share sites, which are the kind of numbers you only see in a theme that has accumulated features over years rather than designed them in one pass.

On the performance and SEO side, the claim is 99 out of 100 on mobile and 100 out of 100 on desktop in Google PageSpeed Insights, plus a correct SEO SCHEMA based on JSON-LD. The search index in the topic tags is Algolia, so the theme's search is backed by Algolia rather than by a client side index.

And there is the offline story. The topic tags include pwa and pwa-app, which points to a progressive web app being part of the design, not an afterthought.

The toolchain: a pnpm workspace, UnoCSS, and Go in the mix

The package.json in the root is a substantial piece of project structure, and it is where the theme's complexity shows.

The package is @hugo-fixit/core, private, versioned 1.0.0-beta.4, and described as the Hugo FixIt core theme component source files. The packageManager field pins [email protected], the engines field requires node 22 or newer, and the author is Lruihao.

The scripts reveal the shape of the project. There are dev:demo, dev:test and dev:docs scripts, each delegating to a filtered workspace package or to the Hugo server. The docs script runs hugo server with the --source flag pointing at a sibling fixit-docs directory, plus -D, --disableFastRender, --navigateToChanged and --ignoreCache, which are the flags you need when you want the browser to reflect content edits immediately rather than after a partial rebuild.

The build script is the interesting one. It runs concurrently the demo and test builds, then runs the integration package and then encrypt. So the build is not just a static site build: it produces two example sites, runs an integration step, and then runs a separate encryption step. That encrypt step is the content-encryption feature in the topic tags, and it being a distinct workspace package called encrypt means the encryption tooling is a component of the project rather than a hook in a template.

Styling is done with UnoCSS, and the project publishes its own preset, @hugo-fixit/unocss-preset, in the dev dependencies. A theme that ships its own UnoCSS preset is doing something specific: the preset carries the theme's design tokens so that utility classes used in content match the theme's colour and spacing system, rather than being arbitrary utility classes that clash with it. There is an uno.config.ts at the root and unocss plus unocss:watch scripts.

Then the documentation generation, which is unusually thorough for a Hugo theme. gen:lexers runs a chroma-lexers package, which suggests the theme generates its own syntax highlighting lexers for the code blocks it ships. gen:docs runs a gen-docs package, gen:typedoc runs typedoc for the TypeScript API, and gen:sassdoc runs sassdoc against assets/scss with a .sassdocrc config to produce a SCSS reference. The typedoc.json and the typecheck script, which runs tsc --noEmit against assets/tsconfig.json, confirm there is a real TypeScript layer in the theme's assets.

Linting is eslint with --cache, using the @antfu/eslint-config, and the repository has an eslint.config.ts so the flat config is written in TypeScript. Formatting and git hooks are handled by simple-git-hooks through the prepare script, and the changelog is generated by auto-changelog-plus with a starting date of 2021-12-18, which dates the project's history back to the end of 2021.

One oddity worth noting: there is a go.mod at the root with module github.com/hugo-fixit/FixIt and go 1.20. A Hugo theme with a Go module file is unusual, and it is there for the Hugo modules consumption path, since Hugo Modules is itself a Go module.

Reading the repository, and what the docs site has to answer for you

The top level listing is a good index of what the theme is made of. The Hugo side is layouts/ for templates, content/ for the site's own content, i18n/ for translations, assets/ for the stylesheets, scripts and images, static/ for files served as-is, archetypes/ for content templates, theme.toml for the theme metadata and hugo.toml for the site's own configuration. The images/ directory holds the preview images used in the README header.

The modern side is packages/ and apps/. The packages directory holds the workspace packages, which from the scripts are the demo, the test, the integration, the encrypt, the chroma-lexers, the gen-docs and the versioning packages. The apps/ directory is the new top level application structure, and the clean script removes public, resources/_gen and apps/*/public and apps/*/resources/_gen, which tells you the apps directory holds built application output. This is the shape of a v1 rewrite: a flat Hugo site directory in the old layout coexisting with an apps-based structure in the new one, and a build script that produces both.

There is also a build.sh at the root, a vercel.json for the Vercel deployment the demo uses, a .devcontainer/ directory, a .vscode/ directory, a .nvmrc and .npmrc, and a .sassdocrc for the SCSS documentation. A CLAUDE.md at the root, alongside AGENTS.md-style tooling, is a sign that the repository has been set up for AI-assisted work on the rewrite.

What none of the repository tells you is the actual configuration model, and for a theme with this many optional integrations, that is the part you need before adopting. The documentation outline in the README goes Installation, Getting Started, Content Management and Advanced Usage, and the advanced section is where the comment, analytics, search, encryption and PWA settings will be. The v1 migration guide is the other must-read, because the main branch is the v1 code and the question of whether your existing configuration still applies is the first thing to resolve.

The open questions the docs have to answer for you are specific. How the six comment systems are configured, since giscus needs a repository and category configuration while Waline needs a server, and those are not interchangeable setups. How the content encryption workflow works and what it encrypts, since the encrypt step is a build-time package rather than a runtime feature and you need to know whether your source content ends up in the repository in encrypted or plain form. And what the UnoCSS preset means for your own content, since if you write utility classes in your Markdown you are depending on the theme's token set.

Editorial conclusion

FixIt fits a Hugo author who wants a feature rich theme with a documented configuration model, several comment backends to choose from and offline support, and who is comfortable with a theme that ships its own styling toolchain. It is the wrong choice if you need a stable release today, since the main branch is v1 code with 1.0.0 planned for the first half of 2027 and the current tags are beta, and it is the wrong choice if you want a theme with a small dependency footprint. Before adopting, read the v1 migration guide linked in the warning, check the Hugo version requirement of 0.166.0 or newer against your toolchain, and decide which comment backend you will use, since the theme ships seven and the configuration is not the same for each.

Frequently asked questions

Official sources

1. hugo-fixit/FixIt on GitHub
2. License: MIT
3. Project website
4. README
5. Releases