# Blowfish: a Hugo theme for engineers who want a landing page and a blog from one config

> Blowfish is an MIT-licensed Hugo theme built on Tailwind CSS 4, aimed at people who want a personal site, documentation pages and a blog from the same content directory. The trade-off is a large feature surface and an install path that assumes you are comfortable with Hugo's module or submodule mechanics.

**nunocoracao/blowfish** — Personal Website & Blog Theme for Hugo

- Repository: https://github.com/nunocoracao/blowfish
- Website: https://blowfish.page
- Stars: 2,904 · Forks: 752
- Language: HTML
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/en/projects/nunocoracao-blowfish

## The gap Blowfish fills between a blog theme and a marketing site

Most Hugo themes pick a lane. A blog theme gives you post lists and taxonomies and leaves you to hand-build anything that looks like a product page. A landing page theme gives you hero sections and feature grids and treats articles as an afterthought. Blowfish tries to cover both from one install: the README lists multiple homepage layouts, including what it calls a product-style landing page with hero image, stats and feature grids, alongside the usual article machinery of related articles, multiple authors and series. The intended user is someone maintaining a personal site where a handful of pages need to sell something and the rest is writing. The theme also targets people who want documentation and blog content in the same repository, since it advertises flexible content types, taxonomies and menus plus nested menus and sub-navigation. If your site is only a changelog or only a set of API reference pages, the homepage layouts are dead weight you will never configure.

## What the repository layout tells you about how Blowfish is assembled

The theme is not a single bundled stylesheet. The repository root contains assets/, layouts/, i18n/, data/, archetypes/ and static/, which is the standard Hugo theme shape, plus a Tailwind layer: tailwind.config.js, assets/css/main.css and a compiled output under assets/css/compiled/. The package.json scripts show the build step explicitly. The dev script runs the Tailwind CLI with -i ./assets/css/main.css -o ./assets/css/compiled/main.css and a watch flag; the build script does the same with NODE_ENV=production. There are separate dev-windows and build-windows variants that set the environment variable with set instead of the POSIX inline form, which is a small but real signal that Windows contributors are expected. go.mod declares the module path github.com/nunocoracao/blowfish/v3, which is what makes the Hugo Module install path possible. The theme also carries its own exampleSite/ directory, and the package.json example script serves it with hugo server -E -F --minify --source exampleSite --themesDir ../.. --buildDrafts -b http://localhost/ -p 1313. That is how the maintainer previews changes. Client-side search is handled by Fuse.js, charts by Chart.js and diagrams by Mermaid, all loaded in the browser rather than pre-rendered.

## Installing Blowfish and getting a first page rendered

The README points at the installation docs and then gives quick starts. The fastest path if you have Node.js, Git and Hugo installed and a Hugo project already created is the blowfish-tools CLI, installed globally from npm.

```bash
npm i -g blowfish-tools
```

Running the bare command starts an interactive run that walks through creation and configuration use cases.

```bash
blowfish-tools
```

If you would rather skip the prompts, the same CLI can create a new Hugo project and install the theme in one step.

```bash
blowfish-tools new mynewsite
```

The manual path uses git submodules. From your project directory you initialise git, then add the theme under themes/blowfish.

```bash
git init
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
```

The README's next instruction is to delete the hugo.toml that Hugo generated in the site root, at which point the excerpt stops. The full sequence, including what replaces that config file, lives on the installation page. Expect to copy configuration out of the theme's config/ directory rather than write it from scratch. The repository also ships an agent skill under .claude/skills/blowfish, installable from the Blowfish plugin marketplace in Claude Code, which the README says teaches an AI coding agent to install, configure and build sites with the theme. That is a genuine convenience, but it is also a signal about how much configuration the theme expects: enough that the maintainer wrote a skill to automate it.

## The Tailwind build is the constraint, not the feature list

The feature list is long, and long feature lists usually hide a build dependency. Here the dependency is visible. Blowfish compiles its own CSS, and package.json wires that compilation into dev, build, dev-windows and build-windows scripts plus a postinstall that runs vendor-copy and an assets script that wipes assets/vendor before re-copying it. If you install the theme as a submodule and then edit anything under assets/css/, you are expected to run the Tailwind CLI yourself, which means Node and npm are part of your site's toolchain even though Hugo itself is a single binary. The README badge states a minimum Hugo version of 0.162.0, so an older Hugo will fail before Tailwind even enters the picture. The theme also claims Lighthouse scores, and lighthouserc.js plus a lighthouse script running lhci autorun exist in the repository, but those measure the maintainer's exampleSite with its own content and configuration. Your site's numbers depend on what you put in it. Treat the score claim as a statement about the reference build, not a property you inherit.

## Where Blowfish is the wrong choice

Two cases stand out. The first is a site that must build without a Node toolchain, for example a locked-down CI runner that only has Hugo. The theme's CSS is compiled and committed, so a plain Hugo build may work, but any customisation that touches the Tailwind source pulls in npm. The second is a site whose value is entirely in the article body and whose author does not want to make layout decisions. Blowfish ships 40 or more shortcodes, GitHub Alerts with 15 types, Mermaid, Chart.js, KaTeX, TypeIt and a Firebase-backed views and likes mechanism. Each is optional, but each is also a surface where a misconfigured key or a missing script changes page behaviour. The views and likes feature in particular depends on Firebase, which the README lists as an integration for dynamic data; a static site with no Firebase project cannot use it. If you want a theme you configure once and forget, the breadth here works against you. There is also the documentation dependency: the README is a quick start and repeatedly defers to blowfish.page/docs, so you will be reading a separate site while setting up.

## How Blowfish differs from the theme you are probably comparing it to

The obvious alternative is PaperMod, the other widely used Hugo theme for personal blogs. The difference is in the build model. PaperMod ships CSS that you consume as-is; you override with plain CSS or by replacing partials. Blowfish ships Tailwind source and expects you to rebuild, which is why package.json exists at the theme root at all. That gives you a design system: colour schemes defined in Tailwind terms, dark mode as a forced, disabled or auto-switching setting, and layouts that share the same utility classes. It also means a change to spacing or colour is a config edit rather than a stylesheet override, and a change to something the theme did not anticipate is a rebuild plus a Tailwind config edit. The other difference is scope. PaperMod is a blog theme. Blowfish is a blog theme plus a landing page builder plus a shortcode library, and it carries the agent skill and CLI tooling to match. Pick by how much of your site is not an article.

## Maintenance, licensing and what upgrading actually costs

The repository is not archived and the last push was on 2026-09-23. Releases are frequent and versioned: v3.5.0, v3.6.0 and a v3.7.0 release, with package.json version at 3.7.0 and go.mod declaring the /v3 module path. That module path matters for upgrade cost. If you install as a Hugo Module, the major version is pinned in the import path, so a future v4 would be an explicit change rather than a silent pull. If you install as a git submodule, you upgrade by moving the submodule pointer, and the README's -b main flag means a fresh clone tracks the main branch rather than a tag; pinning to a release tag is a deliberate extra step. The agent skill and the CLI are separate distribution channels with their own release cadence, so a theme upgrade and a tools upgrade are not the same operation. The licence is MIT, stated in the README badge and in package.json. MIT is permissive and permits commercial use, but the repository does not spell out what that means for the bundled third-party assets under assets/vendor, which the postinstall script copies in. Check the licences of those vendored files and of any icon set, chart library or font you enable before shipping a commercial site. That is a factual gap in the repository, not legal advice.

## Conclusion

Adopt Blowfish if you already run Hugo and want one theme that covers a blog, a landing page and documentation without writing layout code; the agent skill and the blowfish-tools CLI shorten the setup. Do not adopt it if you want a no-build static site, because the theme ships a Tailwind pipeline driven by package.json scripts and a Node toolchain. Before committing, verify that your Hugo version meets the minimum stated in the README badge (0.162.0), decide between the submodule, Hugo Module and manual install paths, and read the installation page at blowfish.page/docs/installation because the README truncates the submodule steps at the point where it tells you to delete the generated hugo.toml.

## FAQ

### What is Blowfish for Hugo?

Blowfish is a theme for Hugo, described in its README as a personal website and blog theme. It is built with Tailwind CSS and ships multiple homepage layouts, 40 or more shortcodes, client-side search, Mermaid diagrams and Chart.js charts.

### How do I install Blowfish?

The README lists three routes: the blowfish-tools CLI installed with npm i -g blowfish-tools, a git submodule added under themes/blowfish, or a Hugo Module, since go.mod declares the module path github.com/nunocoracao/blowfish/v3. Detailed steps for each are on the installation page at blowfish.page/docs/installation.

### Does Blowfish need Node.js if Hugo is a single binary?

The theme's package.json defines dev, build, dev-windows and build-windows scripts that run the Tailwind CLI against assets/css/main.css and write assets/css/compiled/main.css, plus a postinstall that runs vendor-copy. Customising the Tailwind source therefore requires Node and npm, even though Hugo itself does not.

### What Hugo version does Blowfish require?

The README carries a minimum Hugo version badge reading 0.162.0. Anything older is outside what the repository states it supports.

## Sources

- [License: MIT](https://github.com/nunocoracao/blowfish/blob/main/LICENSE)
- [nunocoracao/blowfish on GitHub](https://github.com/nunocoracao/blowfish)
- [Project website](https://blowfish.page)
- [README](https://github.com/nunocoracao/blowfish/blob/main/README.md)
- [Releases](https://github.com/nunocoracao/blowfish/releases)

---

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