hugo-theme-reimu is a free, MIT-licensed Hugo blog theme styled after the Touhou character Hakurei Reimu, created by D-Sketon and ported from the author's hexo-theme-reimu.
What is hugo-theme-reimu?
hugo-theme-reimu is a Hakurei Reimu–themed blog theme for the Hugo static site generator, developed by D-Sketon and released under the MIT license. It takes normal Hugo content — Markdown posts with front matter, a params.yml theme config, and data files for covers, friends, and vendors — and outputs a responsive blog with sidebar, table of contents, archives page, dark mode, and eight comment system options. The theme reports compatibility with Hugo 0.158.0 and above, and the project also publishes hexo-theme-reimu for Hexo and astro-theme-reimu for Astro.
Key Features
- Comment systems — supports Valine, Waline, Twikoo, Gitalk, Giscus, Disqus, Utterances, and Beaudar; multiple systems can run simultaneously since v0.8.0, with a configurable default.
- Math, code, and diagrams — KaTeX and MathJax3 LaTeX rendering (enable one per post), Mermaid flowcharts, code highlighting with a copy button, and optional copyright appended when copied code exceeds a set character count.
- Search and statistics — Algolia search through a generated algolia.json output file, article read counts from Valine or Waline, and busuanzi visitor counters.
- Music and interaction — APlayer with optional Meting support, Live2D and Live2D-widgets figures, mouse-firework effects, a Reimu custom cursor, and a loading preloader with customizable text.
- Performance and navigation — optional PJAX, Service Worker, Quicklink preloading, image lazy loading, TOC, and a Pace progress bar.
- Design customization — experimental Material You dynamic theme colors sampled from the banner image, CSS-variable theming through internal_theme, Google/local/custom fonts, Iconfont and Font Awesome icons, and configurable max layout width.
- Built-in shortcodes — friendsLink friend cards, internal/external link cards, heat map cards, tag roulette, alert blockquotes, tabs, photo walls, grid layouts, collapse details, and spoiler masks.
- Internationalization — UI strings ship in Simplified Chinese, Traditional Chinese, English, and Japanese, with per-language clipboard messages and comment titles.
Who is it for?
- Touhou fans running a blog — get a Reimu-styled site with themed cursor, taiji icons, and preloader text such as "少女祈祷中..." without building it by hand.
- Hugo users who want an all-in-one theme — combine comments, search, math, music, analytics, and shortcodes in one theme instead of wiring separate integrations.
- Bilingual bloggers — the theme and README are available in Chinese and English, and UI labels include zh-TW and Japanese translations too.
- Bloggers who customize heavily — override vendor CDN sources, inject code into head/body/sidebar, define fonts, and control per-post front matter for banner, cover, sidebar, TOC, comments, copyright, and sponsor.
What can you do with it?
- Personal bloggers: publish posts with front matter flags for math, Mermaid, sidebar position, TOC, comments, copyright, sponsor, and outdated notices, and get an archive page plus post cards automatically.
- Chinese mainland site owners: show ICP and 网安备案 filing numbers in the footer, plus optional "萌国 ICP" moe filing info, purely from config.
- Self-hosted comment admins: point a Valine or Waline instance at your LeanCloud server, or use a GitHub-based system like Giscus, Gitalk, or Utterances, so readers can comment without commercial SaaS.
- Mobile readers: benefit from a responsive layout, lazy-loaded images, configurable banner srcset that improves mobile LCP, and dark mode that follows the system preference.
How does hugo-theme-reimu work?
Install it as a Hugo Module or as a Git submodule under themes/reimu. After install, copy the theme's config/_default/params.yml into your site config, copy the theme's data folder contents (covers.yml, friends.yml, vendor.yml) to the site data folder, and create the content structure from the _example folder — an archives _index.md is required for the archive page and a post _index.md prevents an empty post index. A starter template, hugo-reimu-template, is offered for users who want to only clone a repo and edit config.
FAQ
Is hugo-theme-reimu free?
Yes. The theme is MIT licensed and free to use. The author accepts voluntary donations through 爱发电 (afdian), but there is no paid tier and no feature is locked.
Which Hugo versions are supported?
The theme is compatible with Hugo 0.158.0 and above. Code highlighting requires markup settings with guessSyntax enabled and noClasses disabled, and math rendering needs Goldmark passthrough delimiters configured in hugo.toml.
Can I use several comment systems on one blog?
Yes. Since v0.8.0 you can enable multiple systems at once; use the comment.default option to pick which one opens first, and set each system's enable flag to true with its credentials in params.yml.
Do math and Mermaid work on every post?
No, they are per-post features. Add math: true or mermaid: true in a post's front matter, and enable the matching engine (KaTeX or MathJax3 — not both) in params.yml. Mermaid zoom can be disabled globally.
What are the requirements for the Material You theme color feature?
The material_theme option adds crossorigin="anonymous" to the banner image element so the browser can sample its dominant color, so the image server must allow cross-origin access or you should proxy images through a CDN that sends CORS headers.
