hexo-butterfly

Hexo Butterfly Theme Skill

Butterfly is a clean card-style Hexo theme based on hexo-theme-melody, offering rich configuration options and tag plugin features.

Trigger Conditions

Activate this skill when the user asks about the following:

Hexo Butterfly theme installation and configuration
Butterfly theme page settings (tags page, categories page, links page, etc.)
Butterfly theme configuration options (navigation, sidebar, code highlighting, comment systems, etc.)
Butterfly tag plugin usage (Note, Gallery, Tabs, Timeline, etc.)
Troubleshooting common Butterfly theme issues
Butterfly advanced features (music player, icon customization, plugin recommendations, etc.)

Quick Reference

Install the theme

# Git 安装（推荐）
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

# NPM 安装（Hexo 5.0+）
npm install hexo-theme-butterfly

# 必装渲染器
npm install hexo-renderer-pug hexo-renderer-stylus --save

Apply the theme

Modify the Hexo root directory _config.yml：

theme: butterfly

Configuration File Management

In the Hexo root directory, create _config.butterfly.yml, and copy the theme's _config.yml contents. Configuration will not be lost when upgrading the theme.

Common Front-Matter

---
title: 文章标题
date: 2024-01-01 12:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
cover: /img/cover.jpg
toc: true
comments: true
---

Create special pages

# 标签页
hexo new page tags
# 然后设置 type: 'tags'

# 分类页
hexo new page categories
# 然后设置 type: 'categories'

# 友链页
hexo new page link
# 然后设置 type: 'link'

Common Tag Plugins

Note callout:

{% note info %}
这是一条信息提示
{% endnote %}

Tabs:

{% tabs 选项卡名 %}
<!-- tab 标签1 -->
内容1
<!-- endtab -->
<!-- tab 标签2 -->
内容2
<!-- endtab -->
{% endtabs %}

Collapsible content:

{% hideToggle 点击展开 %}
隐藏的内容
{% endhideToggle %}

Reference Documentation

Detailed documentation is located in the references/ directory:

getting-started.md - Quick Start: installation, configuration, upgrade
pages.md - Page Configuration: Front-Matter, special pages, data management
configuration.md - Theme Configuration: navigation, sidebar, code, comments, analytics, etc.
tag-plugins.md - Tag Plugins: Note, Gallery, Tabs, Timeline, Mermaid, etc.
faq.md - FAQ: rendering errors, configuration errors, version compatibility
advanced.md - Advanced Tutorials: music player, icon customization, plugin recommendations

FAQ Quick Lookup

Issue	Solution
Page displays code instead of rendering	`npm install hexo-renderer-pug hexo-renderer-stylus --save`
Links configuration error	Check the `link.yml` indentation spaces
Error after upgrade	Check whether `_config.butterfly.yml` is missing new configuration items
Abnormal styles after deployment	Run `hexo clean` to clear the cache and regenerate
Word count not working	Install `npm install hexo-wordcount --save`

Resource Links

Official documentation:https://butterfly.js.org/
Theme repository:https://github.com/jerryc127/hexo-theme-butterfly