hexo-theme-butterfly is a modern, card-based Hexo blog theme by JerryC127 that renders Markdown posts into a responsive two-column blog with dark mode, multiple comment systems, and a wide array of built-in widgets.
What is hexo-theme-butterfly?
hexo-theme-butterfly is a free, open-source theme for the Hexo static site generator. It takes Markdown-based blog content and outputs a fully styled website with a two-column layout, card-based design, and responsive styling. The theme is installed by cloning the Git repository into the themes/butterfly directory or via npm install hexo-theme-butterfly; the npm route requires Hexo 5.0.0 or newer. Development is led by JerryC127, and the project is licensed under Apache 2.0. The theme is built on Pug templates and Stylus stylesheets.
What makes hexo-theme-butterfly stand out?
hexo-theme-butterfly packs an unusually large feature set into one theme, all controlled through the _config.yml file:
- Dark mode and reading mode — a night-friendly color scheme and a focused article view that strips away sidebars.
- Seven comment systems — supports Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, and Artalk, and lets you enable two at once.
- Three search backends — Algolia Search, Local Search, and Docsearch are built in.
- Syntax highlighting with four themes — darker, pale night, light, and ocean; code blocks include a copy button, language label, fold/expand, and auto-wrap.
- Math and chart rendering — MathJax and KaTeX for formulas, plus Mermaid and Chart.js for diagrams and charts.
- PWA and performance — progressive web app support, Instantpage prefetching, image lazy loading, and page loading animations.
- Image lightboxes — Medium Zoom and Fancybox are both available.
- Multimedia extras — APlayer/Meting music playback, ABCJS music notation, and background/mouse/typing effects.
Who should use hexo-theme-butterfly?
hexo-theme-butterfly fits content-driven sites that want many features without assembling separate plugins. It is a good match for:
- Technical bloggers — write posts with code-heavy content, using the built-in syntax highlighting, math formulas, and chart plugins.
- Design-conscious personal bloggers — get a polished card-based layout with dark mode, customizable accent colors, and a built-in 404 page.
- Chinese and bilingual writers — use the built-in Traditional/Simplified Chinese switch and the extensive Chinese documentation and community around the theme.
- Bloggers who want zero-cost features — replace a stack of plugins with a single theme that includes comments, search, analytics, and PWA support.
What can you do with hexo-theme-butterfly?
The theme's built-in widgets let you build several types of sites without extra plugins. For example:
- Personal bloggers: publish a solo or multi-author blog with series organization, related articles, and an outdated-post reminder for older content.
- Technical documentation sites: organize tutorials with a table of contents on desktop and mobile, code copy buttons, and built-in search.
- Creative portfolios: customize the accent color, add a music player, and enable background and mouse effects to give the site a distinctive feel.
How does hexo-theme-butterfly work?
Installation follows the standard Hexo theme workflow. Clone the master (stable) or dev branch into themes/butterfly, or run npm install hexo-theme-butterfly for Hexo 5.0+. Set theme: butterfly in the Hexo _config.yml, then install the required renderers with npm install hexo-renderer-pug hexo-renderer-stylus --save. After that, hexo generate produces the full site as static HTML.
Pricing
hexo-theme-butterfly is free and open source under the Apache 2.0 license. There is no paid tier, though the author accepts sponsorships via Stripe.
Alternatives
A few other Hexo themes occupy the same space, though Butterfly's feature count is higher. Examples:
- hexo-theme-next — a minimalist Hexo theme that is also widely used.
- hexo-theme-fluid — a Hexo theme with a material-inspired design.
FAQ
Is hexo-theme-butterfly free?
Yes. The theme is released under the Apache 2.0 license and is completely free to use, modify, and distribute. A sponsor page exists if you want to support development financially.
How do I install hexo-theme-butterfly?
You can clone the repository into your Hexo themes folder using git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly, or install via npm with npm install hexo-theme-butterfly (npm requires Hexo 5.0.0+). Then set theme: butterfly in _config.yml and install the pug/stylus renderers.
Does hexo-theme-butterfly support dark mode?
Yes, dark mode is built in. It also has a reading mode, a TOC on both desktop and mobile, and customizable border styles through the theme settings.
Which comment systems are supported?
The theme supports Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, and Artalk. You can even enable two comment systems simultaneously.
Does it support math formulas?
Yes. Both MathJax and KaTeX are supported, so you can render LaTeX-style formulas in your Markdown posts. Chart.js and Mermaid are also included for diagrams and data visualizations.
