A modern, elegant, and feature-rich theme for Hexo
📢 Demo: Official Site | CrazyWong's Blog
- Hexo: 5.3.0 or later
- Node.js: 18 or later (
hexo-util4.x requires it) - Git: only needed for Git installs
💡 Tip: If GitHub access is slow from mainland China, use the Gitee mirror.
Run the following in your Hexo blog root:
# Stable release (recommended)
git clone -b master --depth 1 https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly# Development branch (early access to new features)
git clone -b dev --depth 1 https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly📁 If
themes/butterflyalready exists, remove or rename it first;git clonewill fail if the target folder isn't empty.
npm install hexo-theme-butterfly
⚠️ Note: npm doesn't create a folder underthemes/; the theme goes intonode_modules/instead.
-
Enable the theme: set it in the
_config.ymlat your Hexo root:theme: butterfly
-
Copy the theme config (recommended, so upgrades don't overwrite your settings):
# Git install cp themes/butterfly/_config.yml _config.butterfly.yml # npm install cp node_modules/hexo-theme-butterfly/_config.yml _config.butterfly.yml
💡 Hexo 5+ automatically loads
_config.butterfly.ymlfrom the blog root. On Windows, usecopy themes\butterfly\_config.yml _config.butterfly.ymlfor Git installs, orcopy node_modules\hexo-theme-butterfly\_config.yml _config.butterfly.ymlfor npm installs.⚠️ After this, edit only_config.butterfly.yml. Don't delete the theme's own_config.yml, and keep custom files and images out of the theme'ssource/folder — upgrades may overwrite them. -
Install the renderers and preview locally:
npm install hexo-renderer-pug hexo-renderer-stylus --save hexo clean && hexo s
Git install
cd themes/butterfly
git pullnpm install
npm update hexo-theme-butterflyBefore upgrading, back up your config. After upgrading, check Releases for _config changes and merge them into _config.butterfly.yml.
💡 All features can be configured in
_config.butterfly.yml. See the theme configuration docs for details.
- ✅ Card-based design — Modern card layout
- ✅ Rounded or square corners — Configurable corner radius
- ✅ Responsive layout — Looks great on any screen size
- ✅ Two-column layout — Optimized for reading
- ✅ Dark mode — Easy on the eyes at night
- ✅ Multi-level menu — Nested navigation menus
- ✅ Reading mode — Distraction-free reading
- ✅ Table of contents — Available on desktop and mobile
- ✅ Word count — Shows the word count and estimated reading time
- ✅ Related posts — Smart recommendations at the end of a post
- ✅ Outdated post warning — Alerts readers when a post may be out of date
- ✅ Traditional/Simplified Chinese — Convert between Traditional and Simplified Chinese
- ✅ Tag plugins — Extra tags for richer content
- ✅ Multiple search options — Algolia, local search, or DocSearch
- ✅ Built-in 404 page — A polished error page
- ✅ PJAX — Smooth page transitions
- ✅ Syntax highlighting — Several built-in themes (darker, pale night, light, ocean)
- ✅ Code block tools — Language labels, folding, copy button, word wrap
- ✅ Math formulas — MathJax and KaTeX support
- ✅ Multiple comment systems — Disqus, Gitalk, Valine, Waline, Twikoo, Giscus, Artalk, and more
- ✅ Two comment systems at once — Use two systems side by side
- ✅ Sharing — Share.js and AddToAny
- ✅ Live chat — Chatra, Tidio, or Crisp
- ✅ Visit counter — Busuanzi
- ✅ Site analytics — Google Analytics, Baidu Analytics, Cloudflare Analytics, Microsoft Clarity, or Umami
- ✅ Search engine verification — Google and Baidu
- ✅ Ads — Google AdSense and custom ad slots
- ✅ Typing effects — activate_power_mode animations
- ✅ Background effects — Static, dynamic, or fluttering ribbons, plus Canvas Nest
- ✅ Mouse effects — Fireworks, hearts, and text on click
- ✅ Loading animations — Preloader or a pace.js progress bar
- ✅ Image lightbox — medium-zoom or Fancybox
- ✅ Lazy loading — Images load as they enter the viewport
- ✅ PWA — Progressive Web App support
- ✅ Copy protection — Disable copying or append a copyright notice
- ✅ Theme customization — Custom color schemes
- ✅ Charts — Mermaid flowcharts and Chart.js charts
- ✅ Music notation — ABCJS support
- ✅ Post series — Group posts into series
- ✅ instant.page — Preload pages for faster navigation
- ✅ Snackbar — Elegant toast notifications
Thanks to everyone who has contributed to Butterfly!
We believe open source thrives on participation. Whether you're a developer, a designer, or a user, you can help make Butterfly better.
- 🐛 Found a bug? → Open an issue and let's fix it together.
- 💡 Have an idea? → Start a discussion to share it.
- 📚 New to Butterfly? → Read the documentation.
- ❓ Stuck? → Check the FAQ for common problems and fixes.
- 📦 What's new? → See Releases for version notes and
_configchanges. - 💬 Want to chat? → Join the Telegram group.
Want to help? Contributions of every kind are welcome:
- Code — Fix bugs, add features, improve performance
- Documentation — Improve docs, translate pages, write tutorials
- Design — UI/UX improvements, color schemes, icons
- Testing — Try new features, report issues, share feedback
- Funding — Sponsor the project to support ongoing development
This project is licensed under the Apache 2.0 License.
This theme is based on hexo-theme-melody. Thanks to its author for the inspiration and solid foundation.
Thanks to everyone who has contributed to Butterfly — your support keeps the theme moving forward.
✨ If you find this theme useful, please give it a ⭐ star! ✨




