hexo-theme-stun: a Hexo theme its own author no longer recommends

The README starts by telling you not to use it

The very first thing in the README of hexo-theme-stun is a warning, and it is not a soft one. The project has been neglected for a long time, the author asks you to avoid using it if possible, and recommends the NexT theme, which is described as continuously maintained, instead.

That is an unusual thing for a project to say about itself, and it changes what an evaluation is about. There is no version here to assess for future support, because the author has already told you the answer. What is left to assess is whether an existing deployment should be kept, and what an adopter who ignores the warning inherits.

The rest of the repository is a capable theme. The description calls it an elegant theme for Hexo, and the README presents it as a pretty and simple Hexo theme. The primary language is Stylus, the templates are Pug, which is why the installation asks for the hexo-renderer-pug package, and the licence is MIT with copyright held by liuyib from 2019 to the present.

The homepage is theme-stun.github.io/docs, the default branch is master, the last push was on 2026-06-13, and the repository is not archived. The releases are v2.8.0 from 2022-11-27, v2.7.0 from 2022-07-11 and v2.6.2 from 2021-01-25, and the version in the package.json is 2.8.0.

The feature list is wide, and mostly integrations

It is worth looking at what the theme actually does, because the width of the list is the reason people liked it and also the reason it is hard to keep current.

The basics are covered: a simple, fast and highly customisable design, responsive layout, a secondary navigation menu, image lazy loading, and code highlighting with a choice of colour schemes. Then there is Pjax support, PWA support, Fancybox for lightbox images, and Quicklink for prefetching on hover.

The maths support is notable, with both MathJax and KaTeX available, which is unusual in a blog theme and is the kind of feature that a technical writer picks a theme for. The comment section is the widest part of the list, supporting Gitalk, Valine, Livere, Disqus and Utterances, so the choice of comment system is a configuration decision rather than a fork. There is a waterfall style gallery page, background effects, and a built-in Google Ads integration that can be switched on in one click.

That last item deserves a note rather than a judgement. Bundling an ad integration into a theme puts an advertising account configuration inside the theme's own settings, which is a decision about the theme's default posture rather than a feature in the usual sense. It is opt-in, but it is shipped.

Behind the features sits a configuration surface that the README describes as very detailed, with the full configuration documentation hosted separately. The repository layout supports that: a _config.yml at the root, a languages/ directory for the translations, a layout/ directory for the templates, source/ for the assets and styles, and a scripts/ directory.

Installation is a clone, a renderer and two lines of config

The installation procedure is short and worth reading closely, because one of the two clone options has a trade-off the README spells out.

You go into the root of your Hexo site and clone the repository into the themes directory, using the repository URL and the target path themes/stun. That command clones everything, and the README notes that many of the files are only needed for developing the project itself and are of no use to an ordinary user. A second option clones only the branch the theme needs to run, with the -b dist flag and the same target path, which gives a smaller checkout of the theme files only.

The README's own comment on that second form is that it is not convenient for updating later, and advises care. That is a fork in the road: a smaller checkout now, or the ability to run git pull later.

The theme also needs a Pug renderer, and the README asks you to install the hexo-renderer-pug package from the Hexo root, saving it as a dependency with npm.

Then the theme is selected in the _config.yml at the root of the site.

theme: stun

And the site is served with a clean and a start.

$ hexo clean && hexo s

Updates are a pull in the theme directory, which assumes the full clone rather than the dist one.

$ cd themes/stun

$ git pull

A theme badge states that it requires Hexo 4.0 or newer, and since Hexo 5 and 6 exist, that requirement is itself a checkpoint to verify before starting.

Configuration and documentation live on a mirrored site

The documentation is not in the repository, and that has consequences for a project in this state.

The README lists two documentation mirrors, GitHub Pages and Gitee Pages, and says they are fully synchronised, so you can pick either. The Chinese documentation is linked from the badges and the English README is a separate file, README_en-US.md, alongside the Chinese README.md. The FAQ lives in the repository as FAQ.md, and the contribution guide is another page on the documentation site, which the README asks you to read before opening a pull request.

The repository also carries a stack of project management files, which shows what the project was built with: a commitlint configuration, a cz-config file for commitizen, an eslintrc, a prettierrc, a stylintrc for the Stylus sources, a CHANGELOG.md, a package-lock.json and a scripts/ directory.

The package.json shows the release machinery, which is standard-version with a conventional commits setup, and a commitizen configuration pointing at a cz-customizable plugin, plus a release:lts script that passes a release-as flag and a release:pre script for prereleases. Linting is standard with a fix variant, and husky hooks run the lint on pre-commit and commitlint on the commit message.

Two details stand out for a theme in this condition. The standard configuration lists globals including hexo, CONFIG, Stun and instantsearch, which tells you the theme expects a global search integration, and the package.json is version 2.8.0, matching the last release, so the published package and the last tag agree.

The browser support table is a 2021 statement

The README includes a browser support table, and reading it is a good way to date the project without looking at the release history.

Internet Explorer is marked as not supported. The supported versions are Edge 12 and later, Firefox 41 and later, Chrome 45 and later, Safari 10 and later and Opera 32 and later. Those are the minimum versions from the era the table was written, and every one of them is well past its end of life, which tells you the table has not been revisited in years.

That matters more than a browser table normally would, because a theme is a bundle of front end code that runs on the reader's device rather than on your server. Nothing in a Hexo build step will warn you that a script in the theme uses an API that a current browser has removed, and the failure mode is a broken page for a subset of readers rather than a build error.

The theme also leans on a set of third-party scripts, Pjax, Fancybox, Quicklink, MathJax, KaTeX, and five different comment systems. Every one of those is a separate project with its own release cycle, and a theme cannot fix a dependency that changes its own API. A maintained theme handles that by bumping the version; an unmaintained one cannot, which is the concrete mechanism behind the warning at the top of the README.

The dependencies status badge in the README points at depfu, which tracks the dependency tree, and the FOSSA badge tracks licensing, so the project was set up to watch for exactly these issues. Whether either was still being watched is another question.

What the alternative actually changes

The README names NexT as the theme to use instead, and it is worth being clear about how the two differ rather than simply ranking them.

The difference in approach is one of strategy. Stun ships a broad set of integrations in a single theme, six comment backends, two maths libraries, Pjax, PWA, a lightbox, prefetching, a gallery and an ad integration, which means a user configures rather than builds, and a large surface of third-party scripts to keep current. NexT is a different, more conventional Hexo theme, and the README's argument for it is that it is continuously maintained rather than any claim about its feature set.

The other alternative is to write a minimal theme of your own, or to use a bare Hexo generator with a plugin for the two or three features you actually want, such as comments. The difference in approach is that you own the template layer, the CSS is yours, and there is no dependency surface beyond what you chose. The cost is that the parts Stun already solves, the maths rendering, the lightbox, the responsive menu and the code highlighting, are yours to maintain.

For an existing Stun deployment the calculus is different again. A working blog does not break because its theme is unmaintained, and the site keeps rendering. The risk is quiet: a dependency changes, a browser drops an API, and the problem appears on a reader's device rather than in your build. The theme is MIT licensed, so keeping a fork of the templates in your own repository is straightforward if you want to own the maintenance.

A judgement about adopting something its author abandoned

The honest reading of this repository is that it is a finished project that stopped, rather than one that is merely slow to release.

The last tagged release is v2.8.0 from 2022-11-27, and the last push was on 2026-06-13, which is recent enough to show that somebody has touched the repository without it being a sign of ongoing support. The releases themselves stopped in 2022. So if you are starting a new Hexo blog today, the maintainer's own advice is the right one, and the work in this article is mostly explaining why that advice exists: a wide integration surface, a dependency tree that nobody is watching, a browser support table that stopped being updated years ago, and a build pipeline that only runs the lint.

If you already run Stun, the question is not whether to migrate but what to check. Verify that your Hexo version is still compatible, since the theme states Hexo 4.0 or newer and a major Hexo upgrade is where a static template breaks. Check the comment system you use, since that is usually a separately hosted service and the least fragile part. And check the maths rendering if you use it, because KaTeX and MathJax both change their markup over time.

The licence is MIT, which means nothing blocks you from forking the templates into your own site and owning the maintenance, and the documentation site and the FAQ still exist for the behaviour of the current version. What does not exist is anyone who will fix a regression for you.

Editorial conclusion

hexo-theme-stun fits an existing site that already runs it and wants to keep the templates it has, and it does not fit a new project, because the maintainer recommends against it in the README itself. Before adopting it anywhere, check that your Hexo version still satisfies the theme badge requirement of Hexo 4.0 or newer, and if you keep it, vendor the templates into your own repository so that a dependency change does not become a broken page for your readers.

Frequently asked questions

Official sources

1. License: MIT
2. liuyib/hexo-theme-stun on GitHub
3. Project website
4. README
5. Releases