hexo-theme-reimu: a feature-heavy Hexo blog theme in the Touhou Reimu style

What the theme is, and the family it belongs to

hexo-theme-reimu is a Hakurei Reimu style Hexo theme, written in JavaScript and published to npm as hexo-theme-reimu, with the MIT licence.

The interesting structural fact is that it is one of three. The project maintains a Hexo theme, a Hugo theme called hugo-theme-reimu and an Astro theme called astro-theme-reimu, and the three sit in a table in the project documentation with their version badges side by side. That is an unusual amount of maintenance for a personal theme, and it changes the nature of the project. The design is not a one-off skin for one generator, it is a piece of visual identity that has been ported, which means the theme's appearance is treated as the product and the generator is treated as one of the targets.

The theme itself is a fusion. The author describes it as combining three existing Hexo themes, the default Hexo theme, Tangyuxian and Shoka, and the attribution is explicit in the documentation, which is the right thing to do for a derivative work.

There is a live demo site, and a development log on the same site which is a more interesting artefact than a demo, because a theme that changes its configuration model over time will break a blog that upgrades blindly, and a log lets you see what changed and when. The last push to the repository was on 2026-10-18, and the published releases are v1.12.6 from 2026-08-02, v1.12.5 from 2026-05-16 and v1.12.4 from 2026-05-03, so the source is moving faster than the packaged versions.

The repository tree is the standard Hexo theme layout, with layout/ for the templates, source/ for the assets, scripts/ for the theme's build-time scripts, languages/ for the internationalisation files, a _config.yml for the theme's own settings, an _example/ directory that the documentation uses as the reference for what a site should look like, and a _screenshot/ directory.

What is in the box, feature by feature

The feature list is long, and it is worth reading as a list of decisions rather than as a list of features, because each entry is a plugin somebody else would otherwise have to install.

The base is a complete blog with responsive layout, dark mode support and internationalisation, compatible with Hexo 6 and above.

For technical writing there is code highlighting with a copy button, KaTeX and MathJax3 for mathematics, and Mermaid for diagrams. Those three cover most of what a reader of a technical blog needs, and each of them is a dependency with its own configuration.

For reading there are two search options, Algolia and a local search, and for comments there are eight backends supported at once: Valine, Waline, Twikoo, Gitalk, Giscus, Disqus, Utterances and Beaudar. Eight is not a feature in itself, it is a set of choices, and a theme that supports them all means a reader can pick the one that does not need a server, or the one that is already running for another blog.

Statistics are covered by article read counts through Valine or Waline, and visitor counts through a third-party service.

The media and interaction side has an APlayer and Meting music player, image lazy loading, a loading animation, and mouse effects including a custom Reimu cursor. There is also Live2D and Live2D-widgets integration, which is the feature that decides whether somebody likes the theme or finds it distracting.

For structure there is a table of contents, PJAX support, a Service Worker implementation, and RSS subscription. PJAX in particular is the one that changes the feel of a site, because it replaces a full page load with a fetch and a DOM swap, which is much faster for a reader on a phone and much more annoying for a reader who wants to scroll to the bottom of a long post.

And the design customisation list is the largest: Iconfont and Font Awesome icon support, a set of built-in tag plugins covering internal and external links, friend links, a heatmap, a tag wheel, tag pages, a photo wall, a grid layout and collapsible panels, dynamic theme colour adaptation, custom containers, an article copyright notice, configurable CDN sources, custom fonts, and a share card feature.

Installing it, and the directory structure the theme expects

Installation is a normal npm install of a Hexo theme:

npm install hexo-theme-reimu --save

or cloning the repository into the themes folder and renaming it to reimu:

git clone https://github.com/D-Sketon/hexo-theme-reimu.git

In the second case you then point the site configuration at it:

theme: reimu

For somebody starting from nothing, the project points at a separate template repository called reimu-template, which comes with hexo, hexo-theme-reimu and other function packages already installed, so the path is clone the repository, install the dependencies, change the configuration.

The structure requirement is the part that trips people up, and the documentation is emphatic about it. To guarantee correct display, you should refer to the _example directory and create the _data, about and friend folders in your own source folder, and the note in parentheses makes the distinction explicit: it is the source folder at the root of the blog, not the source folder inside the theme.

The expected layout is:

source/
├── images/
│   └── favicon.ico        # 网站图标
├── _data/
│   ├── avatar/
│   │   └── avatar.webp    # 头像文件
│   ├── covers.yml         # 文章封面 URL 列表
│   └── covers/            # 文章封面文件夹
├── about/                 # 关于页面
│   └── index.md
├── friend/                # 友链页面
│   ├── index.md
│   └── _data.yml          # 友链数据
└── _posts/                # 文章文件夹
    └── xxxx.md

The _data directory carries the avatar, which is expected to be named avatar.webp by default, and the cover material, with covers.yml holding a list of cover URLs and a covers folder holding the cover images. The about folder supplies the about page as an index.md, and the friend folder supplies the links page, with the friend entries themselves in a _data.yml file that the theme turns into friend cards.

The avatar file name is configurable in the theme's own _config.yml, and the documentation warns that the value should not include a path or the request will 404, because the default already points at the folder.

The configuration model, and the cover precedence rules that matter

The theme has its own _config.yml, separate from the site's, and it is the file you edit for anything about appearance or behaviour.

The cover and banner logic is the most detailed part of the configuration, and it is worth reading carefully because there are four fallbacks in play. The article header image prefers the front matter banner, and if that is not set it uses cover for compatibility. When neither is set, the article header falls back to the global cover in the inner _config.yml, and finally to the global banner. The list card cover prefers the front matter cover, which only takes effect when it is a URL, and when the cover is unset, false, or an rgb(...) colour, it falls back to a random image from source/_data/covers and source/_data/covers.yml. If no random cover is available it falls back to the global banner.

The recommended form separates the two images:

---
title: Hello World
banner: https://example.com/post-header.webp
cover: https://example.com/post-card.webp
---

and the older form, where only cover is set, remains compatible.

Other settings follow the same pattern of a global default overridable per article. The sidebar has a position of left, right or false, a menu toggle, and a show_common option for the article page, and an article can override the position in its front matter, with a higher priority than the global configuration. The table of contents is on by default, can be set per article the same way, and has its own options for list numbering and a minimum and maximum depth. The article summary is off by default and can be shown as a subtitle or as a blockquote. Sticky posts are marked with sticky: true in the front matter.

That per-article override model is the one thing to get used to, and it is a good design: a theme-wide default with a front matter escape hatch, rather than a configuration file that has to be edited for every exception.

Where hexo-theme-reimu is the wrong tool

The first limit is that it is a theme with a strong personality, and the personality is not subtle. A Reimu cursor, Live2D widgets, a music player built into the layout, mouse effects and a colour scheme that adapts to the theme are all things a reader either likes immediately or finds distracting. The theme is not a neutral frame for a blog, and for a site whose subject matter is unrelated to the aesthetic, that is a genuine mismatch rather than a matter of taste.

The second is the maintenance asymmetry between the branch and the package. The last push to the repository was on 2026-10-18 while the published package is 1.12.6 from 2026-08-02, and for a theme that changes its configuration model between versions, a blog that upgrades the package without reading the development log will find that a setting has changed meaning or that a directory is now expected. The documentation does keep a development log, and reading it is part of upgrading.

The third is the dependency weight of the built-in features. Eight comment backends, two search systems, three mathematics and diagram renderers, a music player, a Service Worker and PJAX are a lot of front-end machinery for a blog. Each of them has to be configured, and each one that a site does not use is still shipped, and the Service Worker in particular is the component most likely to cause confusion, because a cached old version of a page surviving a deploy is a hard problem to diagnose from the outside.

The fourth is the PJAX trade-off itself. Fetching a page and swapping the content is much faster to read and much harder to share, to bookmark and to print, and it changes how a reader's back button behaves. A blog whose posts are long and technical, where people link to a specific section, loses something with PJAX that it gains in speed.

And the fifth is the scope of what a theme can do. Everything here is presentation. There is no syndication, no newsletter, no authentication, no comments moderation beyond what the chosen backend provides, and no content pipeline. A site that needs those has a static site generator and a set of plugins, and the theme is only the layer that decides what it looks like.

Editorial conclusion

hexo-theme-reimu is worth trying if you publish a Hexo blog and would rather not assemble a plugin stack yourself, because the search, comments, statistics, code highlighting, mathematics and diagrams are all built in, because the dark mode, internationalisation and responsive layout are handled, and because the sibling ports to Hugo and Astro mean the design is not locked to one static site generator. It is the wrong tool if you want a minimal theme, and it is the wrong tool if you dislike the theme's character. Before you adopt it, check three things: that you are on Hexo 6 or later, since that is the stated compatibility, and that you know the theme expects a particular site structure, since the documentation insists on creating _data, about and friend folders inside the blog's own source directory rather than the theme's; that you read the cover and banner precedence rules, because a card cover falls back to a random image from source/_data/covers when the front matter value is unset, false or an rgb() colour, which is a behaviour that surprises people; and that you check the version, since the published package is 1.12.6 from 2026-08-02 while the last push to the repository was on 2026-10-18, so the branch and the package are not the same vintage.

Frequently asked questions

Official sources

1. D-Sketon/hexo-theme-reimu on GitHub
2. License: MIT
3. Project website
4. README
5. Releases