本文只介绍 butterfly 主题的一般性配置，以从简、从便、轻量、易阅读为前提，故不会将所有的配置都写入。如果需要更丰富的配置，请参考 butterfly 主题原博。

主题安装和应用

安装

Butterfly 主题安装

稳定版【建议】

在您的 Hexo 根目录里

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

升级方法：在主题目录下，运行 git pull

稳定版【建议】

在您的 Hexo 根目录里

1
git clone -b master https://gitee.com/immyw/hexo-theme-butterfly.git themes/butterfly

升级方法：在主题目录下，运行 git pull

此方法只支持 Hexo 5.0.0 以上版本。
通过 npm 安装并不会在 themes 里生成主题文件夹，而是在 node_modules 里生成。

在您的 Hexo 根目录里

1
npm i hexo-theme-butterfly

升级方法：在 Hexo 根目录下，运行 npm update hexo-theme-butterfly

应用主题

主题应用设置

修改 Hexo 根目录下的 _config.yml ，把主题改为 butterfly 。

1
theme: butterfly

安装插件

安装插件

如果你没有 pug 以及 stylus 的渲染器，请下载安装：

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

升级建议

了解主题配置文件

在 hexo 的根目录创建一个文件 _config.butterfly.yml，并把主题目录的 _config.yml 内容复制到 _config.butterfly.yml 去。( 注意: 复制的是主题的 _config.yml ，而不是 hexo 的 _config.yml )。

Hexo会自动合并主题中的 _config.yml 和 _config.butterfly.yml 里的配置，如果存在同名配置，会使用 _config.butterfly.yml 的配置，其优先度较高。

页面配置

Front-matter

Font-matter 是 markdown 文件最上方以 --- 分隔的区域，用于指定个别档案的变数。

Hexo 根目录 \scaffolds\page.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
title:                  # 【必须】页面标题
date:                   # 【必须】页面创建日期
type:                   # 【必须】标签、分类和友情链接三个页面需要配置
updated:                # 【可选】页面更新时间
comments:               # 【可选】显示页面评论模块（默认 true）
description:            # 【可选】页面描述
keywords:               # 【可选】页面关键字
top_img:                # 【可选】页面顶部图片
mathjax:                # 【可选】显示mathjax (当设置mathjax的per_page: false，才需要配置，默认false)
katex:                  # 【可选】显示katex (当设置katex的per_page: false，才需要配置，默认false)
aside:                  # 【可选】显示侧边栏 (默认 true)
aplayer:                # 【可选】在需要的页面加载aplayer的js和css，参考音乐页面配置
highlight_shrink:       # 【可选】配置代码框是否展开 (true/false，默认为设置中的highlight_shrink的配置)
---

Hexo 根目录 \scaffolds\post.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
title:                  # 【必须】文章标题
date:                   # 【必须】文章创建日期
updated:                # 【可选】文章更新日期
tags:                   # 【可选】文章标签
categories:             # 【可选】文章分类
keywords:               # 【可选】文章关键字
description:            # 【可选】文章描述
top_img:                # 【可选】文章顶部图片
comments:               # 【可选】显示文章评论模块 (默认为 true)
cover:                  # 【可选】文章缩略图 (如果没有设置top_img，文章顶部显示缩略图，可设置为 false/图片地址/留空)
toc:                    # 【可选】显示文字TOC (默认为设置中toc的enable配置)
toc_number:             # 【可选】显示toc_number(默认为设置中toc的number配置)
copyright:              # 【可选】显示文章版权模块(默认为设置中post_copyright的enable配置)
copyright_author:       # 【可选】文章版权模块的文章作者
copyright_author_href:  # 【可选】文章版权模块的文章作者链接
copyright_url:          # 【可选】文章版权模块的文章链接
copyright_info:         # 【可选】文章版权模块的版权声明文字
mathjax:                # 【可选】显示mathjax (当设置 mathjax 的 per_page: false 时，才需要配置，默认 false )
katex:                  # 【可选】显示katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false )
aplayer:                # 【可选】在需要的页面加载 aplayer 的 js 和 css,请参考文章下面的音乐 配置
highlight_shrink:       # 【可选】配置代码框是否展开(true/false)(默认为设置中 highlight_shrink 的配置)
aside:                  # 【可选】显示侧边栏 (默认 true)
---

标签页

标签页设置
  1. 前往您的 Hexo 博客的根目录
  2. 输入 hexo new page tags
  3. 找到 source/tags/index.md 这个文件
  4. 修改这个文件，加上 type: "tags"
1
2
3
4
5
---
title: tags
date: 2023-11-11 17:03:49
type: "tags" # 记得添加改行
---

分类页

分类页设置
  1. 前往您的 Hexo 博客的根目录
  2. 输入 hexo new page categories
  3. 找到 source/categories/index.md 这个文件
  4. 修改这个文件，加上 type: "categories"
1
2
3
4
5
---
title: categories
date: 2023-11-11 17:07:28
type: "categories"
---

友情链接

友情链接设置。
  1. 前往您的 Hexo 博客的根目录
  2. 输入 hexo new page link
  3. 找到 source/link/index.md 这个文件
  4. 修改这个文件，加上 source/link/index.md
1
2
3
4
5
---
title: link
date: 2023-11-11 17:13:17
type: "link"
---

在Hexo博客目录中的 source/_data（如果没有 _data 文件夹，请自行创建），创建一个文件 link.yml，参考修改如下配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、简单且强大的网志框架

- class_name: 网站
  class_desc: 值得推荐的网站
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: 视频网站
    - name: Weibo
      link: https://www.weibo.com/
      avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
      descr: 中国最大社交分享平台
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: 社交分享平台

404 页面

主题内置了一个简单的 404 页面，可在设置中开启。
  • 在 _config.butterfly.yml 文件中查找 error_404。
1
2
3
4
5
# A simple 404 page
error_404:
  enable: true
  subtitle: "页面没有找到"
  background:

网站资料

默认语言

修改站点配置文件：_config.yml，默认语言是 en 。

主题支持三种语言：

  • default（en）
  • zh-CN（简体中文）√
  • zh-TW（繁体中文）

网站个人资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，修改博客根目录的 _config.yml 。
1
2
3
4
5
6
7
title: wmJim's Blog         # 网站主标题
subtitle: ''                # 网站副标题
description: ''             # 网站描述
keywords: C++/C/Rust        # 搜索关键词
author: wmJim               # 作者
language: zh-CN             # 语言
timezone: Asia/Shanghai     # 时区

导航栏设置

修改主题配置文件 _config.butterfly.yml 。

导航栏参数设置
1
2
3
4
nav:
  logo:                     # 网站的 logo，支持图片，直接填入图片链接
  display_title: true       # 是否显示网站标题，填写 true 或者 false
  fixed: false              # 是否固定状态栏，填写 true 或者 false
修改导航栏菜单

这部分可以参考，但是要根据自己设置的情况去写，否则链接是无效的。

1
2
3
4
5
6
7
8
9
10
11
menu:
  首页: / || fas fa-house
  时间轴: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  清单||fas fa-list:
    待办清单: /project/ || fas fa-check
    留言板: /comments/ || fas fa-comments
    藏书阁: /books/ || fas fa-book
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart
  • 必须是 /xxx/，后面||分开，然后写图标名。
  • 如果不希望显示图标，图标名可不写。
  • 默认子目录是展开的，如果你想要隐藏，在子目录里添加 hide 。

代码

1
highlight_theme: mac # 我个人推荐 mac 样式

1
highlight_copy: true
1
highlight_shrink: false # 我的推荐
  • true 全部代码框不展开，需点击 > 进行展开
  • false 代码框展开，有 > 关闭展开按钮
  • none 不显示 > 按钮

在默认情况下，Hexo 在编译的时候不会实现代码自动换行。如果你不希望在代码块的区域里有横向滚动条的话，那么你可以考虑开启这个功能。


1
code_word_wrap: false # 我推荐关闭这个功能

  • 如果你是使用 highlight 渲染，需要找到你站点的 Hexo 配置文件_config.yml，将 line_number 改成 false:

    • </ul>
    1
    2
    3
    4
    5
    highlight:
      enable: true
      line_number: false # <- 改这里
      auto_detect: false
      tab_replace:

    • 如果你是使用 prismjs 渲染，需要找到你站点的 Hexo 配置文件_config.yml，将 line_number 改成 false:

      • </ul>
      1
      2
      3
      4
      5
      prismjs:
        enable: false
        preprocess: true
        line_number: false # <- 改这里
        tab_replace: ''

可配置代码高度限制，超出的部分会隐藏，并显示展开按钮。


1
highlight_height_limit: 500 # 个人推荐高度

  1. 单位是 px，直接添加数字，如 200
  2. 实际限制高度为 highlight_height_limit + 30 px ，多增加 30px 限制，目的是避免代码高度只超出 highlight_height_limit 一点时，出现展开按钮，展开没内容。
  3. 不适用于隐藏后的代码块（ css 设置 display: none）

社交图标

社交图标配置

书写格式 图标名：url || 描述性文字，可以参考我的设置。

1
2
3
social:
  fab fa-github: https://github.com/wmJim || Github || '#24292e'
  fas fa-envelope: mailto:meng.w1016@outlook.com || Email || '#4a7dbe'

头像

头像配置
1
2
3
avatar:
  img: /img/avatar.png
  effect: true # 鼠标移至头像，头像会一直转圈

顶部图

顶部图配置

如果不要显示顶部图，可直接配置 disable_top_img: true

可配置的值：

配置解释
index_img主页的 top_img
default_top_img默认的 top_img，当页面的 top_img 没有配置时，会显示 default_top_img
archive_img归档页面的 top_img
tag_imgtag 子页面 的 默认 top_img
tag_per_imgtag 子页面的 top_img，可配置每个 tag 的 top_img
category_imgcategory 子页面 的 默认 top_img
category_per_imgcategory 子页面的 top_img，可配置每个 category 的 top_img

以上所有的 top_img 可配置以下值：

配置的值效果
留空显示默认的 top_img（如有），否则显示默认的顔色
img 链接图片的链接，显示所配置的图片
顔色 (
HEX 值 - #0000FF
RGB 值 - rgb (0,0,255)
顔色单词 - orange
渐变色 - linear-gradient (135deg, #E2B0FF 10%, #9F44D3 100%)
）		对应的颜色
transparent透明
false不显示 top_img

文章封面

文章封面配置

文章封面的获取顺序 Front-matter 的 cover > 配置文件的 default_cover > false

自己按需配置，以下是我的配置。

1
2
3
4
5
6
7
8
9
cover:
  index_enable: true        # 主页是否显示文章封面图
  aside_enable: false       # 侧栏是否显示文章封面图
  archives_enable: false    # 归档页面是否显示文章封面图
  # 封面的显示位置
  # left/right/both left，全部显示在左边; right，全部显示在右边; both，左右轮流显示
  position: both
  # 当没有设置cover时，默认的封面显示
  default_cover:

文章页相关配置

这个选项是用来显示文章的相关信息的。

1
2
3
4
5
6
7
8
9
10
11
12
13
post_meta:
  page:
    date_type: created          # created or updated or both 主页文章日期是创建日或者更新日或都显示
    date_format: date           # date/relative 显示日期还是相对日期
    categories: true            # true or false 主页是否显示分类
    tags: true                  # true or false 主页是否显示标签
    label: true                 # true or false 显示描述性文字
  post:
    date_type: both             # created or updated or both 文章页日期是创建日或者更新日或都显示
    date_format: date           # date/relative 显示日期还是相对日期
    categories: true            # true or false 文章页是否显示分类
    tags: true                  # true or false 文章页是否显示标签
    label: true                 # true or false 显示描述性文字

为你的博客文章展示文章版权和许可协议。

1
2
3
4
5
6
post_copyright:
  enable: true
  decode: false
  author_href:
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

相关二维码可以自行配置。

1
2
3
4
5
6
7
8
9
reward:
  enable: true
  QR_code:
    - img: /img/wechat.png
      link:
      text: wechat
    - img: /img/alipay.png
      link:
      text: alipay

在文章页，会有一个目录，用于显示 TOC。

1
2
3
4
5
6
7
toc:
  post: true            # 文章页是否显示 TOC
  page: false           # 普通页面是否显示 TOC
  number: true          # 是否显示章节数
  expand: false         # 是否展开 TOC
  style_simple: true    # 简洁模式
  scroll_percent: false # 是否显示滚动百分比

相关文章推荐的原理是根据文章 tags 的比重来推荐

1
2
3
4
related_post:
  enable: true
  limit: 6             # 显示推荐文章数目
  date_type: created   # created or updated 文章日期显示创建日或者更新日

开启文章锚点后，当你在文章页进行滚动时，文章链接会根据标题 ID 进行替换

(注意：每替换一次，会留下一个历史记录。所以如果一篇文章有很多锚点的话，网页的历史记录会很多。)

因此，我的选择就是不开启。

1
2
3
4
5
6
anchor:
  button:
    enable: false
    always_show: false
    icon: 
  auto_update: false

可设置分页的逻辑，也可以关闭分页显示

1
2
3
4
# 1: 下一篇显示的是旧文章
# 2: 下一篇显示的是新文章
# false: 关闭文章分页
post_pagination: 2

主页文章节选

主页文章节选配置

在 butterfly 里，有四种可供选择:

  1. description： 只显示 description
  2. both： 优先选择 description，如果没有配置 description，则显示自动节选的内容
  3. auto_excerpt：只显示自动节选
  4. false： 不显示文章内容
1
2
3
index_post_content:
  method: 2
  length: 500 # if you set method to 2 or 3, the length need to config

图片描述

图片描述

可开启图片Figcaption描述文字显示，我觉得没用就给关了：

1
photofigcaption: false

复制相关配置

复制相关配置

可配置网站是否可以复制、复制的内容是否添加版权信息。

1
2
3
4
5
copy:
  enable: true          # 是否开启网站复制权限
  copyright:            # 复制的内容后面加上版权信息
    enable: true        # 是否开启复制版权信息添加
    limit_count: 300    # 字数限制，当复制文字大于这个字数限制时，将在复制的内容后面加上版权信息
Footer 设置
  • since是一个来展示你站点起始时间的选项。它位于页面的最底部。
  • custom_text是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等。
1
2
3
4
5
6
footer:
  owner:
    enable: true
    since: 2023     # 博客年份
  custom_text:  Hi, welcome to my <a href="https://www.wmjim.cn/">blog</a>!
  copyright: true   # Copyright of theme and framework
  • 对于部分人需要写 ICP 的，也可以写在 custom_text里
1
custom_text: <a href="icp链接"><img class="icp-icon" src="icp图片"><span>备案号：xxxxxx</span></a>

侧边栏设置

需要关注的几个点，我用注释进行说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
aside:
  enable: true          # 是否开启侧边栏
  hide: false           # 
  button: true
  mobile: true          # 手机页面（ 显示宽度 < 768px ）是否显示aside内容
  position: right       # left(侧边栏在左) or right(侧边栏在右)
  display:
    archive: true       # 文章
    tag: true           # 标签
    category: true      # 分类
  card_author:
    enable: true        # 作者
    description:        # 作者的描述
    button:             # Follow Me 按钮
      enable: true
      icon: fab fa-github
      text: Follow Me
      link: https://github.com/wmJim
  card_announcement:    # 公告内容
    enable: true
    content: 'Hi，欢迎您来到我的博客小世界~<br>记录我的所学、所思、所想<br>个人微信: 18569814350<br>期望带给你愉快的阅读体验！！！'
  card_recent_post:     # 最近文章
    enable: true
    limit: 5 # if set 0 will show all
    sort: date # date or updated
    sort_order: # Don't modify the setting unless you know how it works
  card_categories:     # 分类
    enable: true
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
    sort_order: # Don't modify the setting unless you know how it works
  card_tags:           # 标签 
    enable: true
    limit: 40 # if set 0 will show all
    color: true
    orderby: random # Order of tags, random/name/length
    order: 1 # Sort of order. 1, asc for ascending; -1, desc for descending
    sort_order: # Don't modify the setting unless you know how it works
  card_archives:       # 归档
    enable: true
    type: monthly # yearly or monthly
    format: MMMM YYYY # eg: YYYY年MM月
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending
    limit: 8 # if set 0 will show all
    sort_order: # Don't modify the setting unless you know how it works
  card_webinfo:       # 网站咨询
    enable: true
    post_count: true
    last_push_date: true
    sort_order: # Don't modify the setting unless you know how it works

直接全部打开即可

1
2
3
4
busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

网站运行时间打开

1
2
3
runtimeshow:
  enable: true
  publish_date: 9/13/2023 00:00:00    # 网站上线日期，自行设置

右下角按钮

1
2
3
4
5
6
7
8
9
10
11
12
translate:
  enable: true
  # 默认按钮显示文字(网站是简体，应设置为'default: 繁')
  default: 繁
  # 网站默认语言，1: 繁体中文, 2: 简体中文
  defaultEncoding: 2
  # 延迟时间,若不在前, 要设定延迟翻译时间, 如100表示100ms,默认为0
  translateDelay: 0
  # 当文字是简体时，按钮显示的文字
  msgToTraditionalChinese: '繁'
  # 当文字是繁体时，按钮显示的文字
  msgToSimplifiedChinese: '简'
1
2
3
4
5
6
# dark mode
darkmode:
  enable: true
  # dark mode和 light mode切换按钮
  button: true
  autoChangeMode: false # 取消自动切换

阅读模式下会去掉除文章外的内容，避免干扰阅读。

1
readmode: true

可以改变字体大小（最小隻能到 10px，最大隻能到 20px）

1
change_font_size: true

总结

关于 buttfly 主题的一般性配置就介绍到这里，完成这些设置博客网站就基本上可以投入文章记录和运营了。后面将专门开两篇文章介绍 butterfly 主题的标签外挂和 butterfly 主题的高级配置。