hexo-theme-butterfly: a card-style Hexo theme for content-heavy blogs

What Butterfly solves for a Hexo blog

Hexo ships a bare theme. Writing a post is easy; making the site look finished is not. Butterfly's pitch is that the finished parts come as configuration rather than as a plugin hunt. The README lists the features it bundles: multiple comment systems (Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, Artalk), search options (Algolia, local search, Docsearch), analytics (Google, Baidu, Cloudflare, Microsoft Clarity, Umami), image lightboxes, math rendering, PWA support and a dark mode. You edit one theme config file instead of wiring four plugins together and hoping their versions agree.

The audience is the blogger who publishes long, illustrated posts and wants a two-column reading layout with a table of contents. The README describes the layout as card-based, with rounded or square borders, and calls out a two-column layout as an optimized reading experience. If your blog is a landing page for a product, or a docs site generated from Markdown with a sidebar tree, this is not the shape you want. Butterfly is built around posts, tags, categories and archives.

How the theme is put together

The repository layout tells you the architecture before you read any docs. There is layout/, which holds the Pug templates that produce the HTML, and source/, which holds the assets. languages/ contains the translation files, which is why the README can advertise Traditional and Simplified Chinese switching. scripts/ holds the Hexo scripts the theme injects at build time, and plugins.yml is a separate manifest for the plugin part of the theme.

package.json names the runtime dependencies: hexo-renderer-pug, hexo-renderer-stylus, hexo-util and moment-timezone. That is the whole build story. Pug compiles the templates, Stylus compiles the stylesheets, and moment-timezone is there for date handling. Nothing is precompiled and shipped as a bundle, so a Hexo build runs the compilers on your machine. The practical consequence is that a Butterfly site is a build-time artifact: every deploy re-renders the templates, and a Pug syntax error in a template you edited shows up as a failed build, not as a broken page in the browser.

The package.json also has a test script that does nothing but print an error and exit 1. There is no test suite in the repository. For a theme that is mostly templates and CSS, that is a normal trade-off, but it means a config change is validated by building the site and looking at it, not by running a check.

Installing Butterfly and getting a first build

The README gives two install methods. The git method is the recommended one and clones into themes/butterfly from your Hexo blog root. The master branch is the stable version; the dev branch gets new features early. Run one of these from the blog root, not from inside themes/:

git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

After the clone, themes/butterfly should exist next to your source/ and _config.yml. The README notes a Gitee mirror for readers in mainland China where GitHub access is slow.

The npm route is shorter but has a version condition: the README states that npm installation only supports Hexo 5.0.0 and above.

npm install hexo-theme-butterfly

Either way, you then point Hexo at the theme by editing the blog's _config.yml:

theme: butterfly

Finally, install the renderers the theme depends on if they are not already present:

npm install hexo-renderer-pug hexo-renderer-stylus --save

Run hexo clean followed by hexo server and open the local address Hexo prints. If the page renders unstyled, the Stylus renderer is the first thing to check; if the build fails on a template, the Pug renderer is.

Where Butterfly gets in your way

The feature list is also the configuration burden. Comment systems, search backends, analytics providers, ad slots and chat widgets each have their own settings, and each one you enable is a third-party script on every page. The README does not document a way to audit what a given configuration actually loads, so the cost of turning things on is only visible in the rendered page source.

The theme is also opinionated about the site it renders. The README describes built-in 404, Pjax support and instantpage preloading as features. Those assume a particular kind of site: one where a 404 page is a design surface and where client-side navigation is desirable. If you are serving a small static site behind a CDN with strict caching rules, Pjax changes what gets requested and when, and that is a behaviour you have to reason about rather than a checkbox.

The versioning is the third friction point. The repository's default branch is dev, and the README treats dev as early access to new features. Anyone who clones the default branch without specifying -b master is tracking development. The README's own install command uses -b master, which is the right default, but the repository's branch setting points the other way.

Finally, the package.json test script exits with an error. There is no automated check to tell you that your config is valid.

Butterfly against the other Hexo themes people compare it with

The searches that lead to Butterfly are mostly people weighing Hexo themes against each other: NexT, Fluid, Keep, Matery, Icarus, Cactus, Redefine. The meaningful difference is how much the theme decides for you. NexT and Icarus are long-standing themes with their own configuration schemes and plugin ecosystems; Butterfly's distinguishing choice is to bundle the integrations (comments, search, analytics, lightboxes, charts, music notation) into the theme config so that the site is complete after one install step. Fluid and Keep sit closer to a lighter, more typographic default.

The trade-off is legibility. A theme that bundles more has more configuration keys, and a theme with more configuration keys is harder to reason about when something renders wrong. If you want to read every line of the theme before you trust it, a smaller theme is the better choice, and Butterfly is the wrong one. If you want a blog that looks finished on the day you install it and you are willing to maintain a config file, Butterfly is aimed at you.

Maintenance, upgrades and the Apache-2.0 licence

The last push to the repository was on 2026-08-13, and the most recent release listed is 5.7.0 from 2026-08-04. The repository is not archived. Releases have been reasonably frequent: 5.6.0 on 2026-07-16, 5.6.1 on 2026-07-21, 5.7.0 on 2026-08-04. The package.json version string, 5.7.1.260810, does not match the release tags exactly, so if you install from npm you should check which version you actually received rather than assuming it matches the latest tag.

Upgrade cost depends on your install method. With git, an upgrade is a pull inside themes/butterfly, and any local template edits you made will conflict. With npm, the theme lives in node_modules and local edits are not the expected workflow, but you also lose the ability to patch a template in place. The README does not document a rollback procedure for either path, so keeping your own copy of the theme config and knowing the version you are on is the practical safeguard.

The licence is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It does not oblige you to publish your blog's content or configuration. If you fork the theme and redistribute it, the licence terms apply to the fork. This is a description of the licence text, not legal advice; read the LICENSE file in the repository if the distinction matters to you.

Editorial conclusion

Adopt Butterfly if you run a Hexo blog and want search, comment systems, analytics and a dark mode wired into the theme rather than assembled from plugins; the npm package and the master branch give you two supported install paths. Do not adopt it if you want a minimal theme you can read end to end, or if you are not on Hexo at all. Before committing, check the documented Hexo version floor of 5.3.0 and the npm note about Hexo 5.0.0 and above, decide whether you will track master or dev, and confirm that the renderer dependencies hexo-renderer-pug and hexo-renderer-stylus are installed in your blog.

Frequently asked questions

Official sources

1. jerryc127/hexo-theme-butterfly on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases