Butterfly

Butterfly is a modern, feature-rich theme for Hexo static site generators that turns markdown source files into a card-based, responsive blog with dark mode and dozens of optional integrations. Maintained by Jerryc127 under the Apache 2.0 license, it has over 8,000 GitHub stars and is one of the most widely adopted Hexo themes.

What is Butterfly?

Butterfly is a Hexo theme that takes your markdown posts and renders a two-column, card-style blog with dark mode, a built-in 404 page, and customizable rounded or square corners. It runs on Hexo 5.3.0 and newer, uses pug templates and stylus stylesheets, and can be installed by cloning the master or dev branch from GitHub or by running npm install hexo-theme-butterfly (npm requires Hexo 5.0.0+). After installation you set theme to butterfly in _config.yml and install the hexo-renderer-pug and hexo-renderer-stylus packages.

Key Features

• Card-based responsive design — two-column layout that adapts to all screen sizes, with dark mode and adjustable border radius settings.
• Multiple search backends — built-in support for Algolia Search, Local Search, and Docsearch so visitors can find posts instantly.
• Rich code display — syntax highlighting with four built-in themes (darker, pale night, light, ocean), plus code folding, copy buttons, language labels, auto-wrap, and MathJax or KaTeX math rendering.
• Many comment systems — Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, and Artalk are supported, and two comment systems can be enabled at the same time.
• Analytics and ads — integrates Google Analytics, Baidu, Cloudflare, Microsoft Clarity, and Umami, along with Busuanzi visit counts, webmaster verification, and Google AdSense or custom ad slots.
• Visual effects — static, dynamic, and floating ribbons, Canvas Nest, click fireworks/hearts/text, typing animation, preloader and pace.js loading bars, Medium Zoom/Fancybox lightboxes, and lazy loading images.
• PWA support — makes the blog installable and offline-capable through progressive web app configuration.
• Content helpers — multi-level menus, reading mode, table of contents for desktop and mobile, word count and reading time, related articles, outdated article reminders, series organization, and Traditional/Simplified Chinese switching.

Who should use Butterfly?

• Hexo bloggers who want a modern card-based design without writing CSS by hand can enable the theme and have a polished blog in minutes.
• Developers who need deep customization can edit the pug templates and stylus stylesheets or toggle dozens of config options for colors, effects, and integrations.
• Multilingual authors benefit from the built-in Traditional/Simplified Chinese switch and English/Chinese documentation.
• Content-heavy sites can wire up Algolia search, multiple comment systems, live chat (Chatra, Tidio, Crisp), and analytics without separate plugins.

What can you do with Butterfly?

• Personal bloggers: publish markdown posts and get a responsive blog with dark mode, TOC, word count, and reading time automatically.
• Tech writers: drop in code blocks and formulas; they render with syntax highlighting, folding, copy buttons, and MathJax/KaTeX support.
• Community builders: enable two comment systems at once and add live chat widgets like Chatra, Tidio, or Crisp to engage readers.
• Visual storytellers: turn on ribbon backgrounds, canvas nest, mouse click effects, and image lightboxes to add animation without custom JS.

How does Butterfly work?

Butterfly is installed by cloning the repository into the themes directory or using npm, then specifying theme: butterfly in the Hexo _config.yml. After installing the pug and stylus renderers, Hexo's normal generate command compiles the theme's templates and your markdown into a static HTML site. The dev branch offers early access to new features while the master branch provides a stable release.

FAQ

Is Butterfly free?

Yes, Butterfly is open source and distributed under the Apache 2.0 license, so it can be used for personal or commercial blogs without licensing fees.

Does Butterfly support dark mode?

Yes, dark mode is a built-in feature that gives an eye-friendly night-time color scheme. You can enable or configure it from the theme settings.

What dependencies does Butterfly need?

At minimum you need hexo-renderer-pug and hexo-renderer-stylus. The npm installation method only works with Hexo 5.0.0 and above; the git clone method works with earlier versions as well.

Which comment systems can I use?

Butterfly supports Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, Artalk, and more. It also allows enabling two comment systems simultaneously, so readers can choose their preferred service.

Is there a demo of Butterfly?

Yes, live demos are available at butterfly.js.org and blog.crazywong.com. The project documentation is hosted at butterfly.js.org with both English and Chinese versions.