Preface

Hexo’s official default theme is quite plain and lacks any extra decorative elements, which is intolerable for a personal blog. This post will provide detailed instructions on how to install and use Hexo themes.

Theme Used

The theme used here as an example, and the one I personally use, is the Butterfly theme.

1️⃣ Official demo site: https://butterfly.js.org/en/

2️⃣ Official GitHub repository: https://github.com/jerryc127/hexo-theme-butterfly

3️⃣ Butterfly’s official installation tutorial: https://butterfly.js.org/posts/21cfbf15/

4️⃣ Hexo theme collection: https://hexo.io/themes/

The installation process for other themes is similar - you can install them according to their respective official documentation.

This tutorial only uses the Butterfly theme as an example. Parameter introductions will be written later.

Installation

The installation process will introduce two methods: one using Git and the other using npm. Choose whichever method you’re comfortable with.

Git Installation

Navigate to your blog’s root directory and run Git Clone: git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly to clone the Butterfly files.

PS: If you want to install the newer dev branch, you can clone the dev branch: git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

Warning: The test version may contain bugs. If you want stability, please install the stable version.

Tip: To upgrade the theme version: run git pull in the theme directory.

Modify the _config.yml file in the Hexo root directory and change the theme to butterfly:

theme: butterfly

If you don’t have the pug and stylus renderers, please download and install them:

npm install hexo-renderer-pug hexo-renderer-stylus --save

When the theme version is updated, the _config file will undergo content changes. To prevent errors after version updates, please create a file named _config.butterfly.yml in the hexo root directory and copy the contents of the theme directory’s _config.yml to _config.butterfly.yml.

Tips:

1. Copy the theme’s _config.yml, not hexo’s _config.yml

2. Don’t delete the theme directory’s _config.yml

3. From now on, you only need to configure in _config.butterfly.yml. If you use _config.butterfly.yml, configuring the theme’s _config.yml will have no effect.

Hexo will automatically merge the configurations from the theme’s _config.yml and _config.butterfly.yml. If there are configurations with the same name, it will use the configuration from _config.butterfly.yml, which has higher priority.

NPM Installation

Tips:

1. This method only supports Hexo version 5.0.0 and above

2. Installing through npm will not generate a theme folder in themes, but will generate it in node_modules instead

Navigate to your blog’s root directory, run npm install hexo-theme-butterfly, and then follow the same steps as in the Git Installation section.