转载自
Butterfly主题作者
Butterfly主题作者
https://butterfly.js.org/

安装

下载主题到项目themes目录下

image-20220625171549579

应用主题

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

1
theme: butterfly

push项目：由于之前写了脚本，双击脚本即可。

初步效果：

image-20220625180639124

安装插件

安装pug、stylus，不知道干嘛用的。

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

页面配置

Front-matter

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

  • Page Front-matter 用于页面配置
  • Post Front-matter 用于文章页配置

Page Front-matte

写法 解释
title 【必需】頁面標題
date 【必需】頁面創建日期
type 【必需】標籤、分類和友情鏈接三個頁面需要配置
updated 【可選】頁面更新日期
description 【可選】頁面描述
keywords 【可選】頁面關鍵字
comments 【可選】顯示頁面評論模塊(默認 true)
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的配置)

Post Front-matter

写法 解释
title 【必需】文章標題
date 【必需】文章創建日期
updated 【可選】文章更新日期
tags 【可選】文章標籤
categories 【可選】文章分類
keywords 【可選】文章關鍵字
description 【可選】文章描述
top_img 【可選】文章頂部圖片
cover 【可選】文章縮略圖(如果沒有設置top_img,文章頁頂部將顯示縮略圖，可設為false/圖片地址/留空)
comments 【可選】顯示文章評論模塊(默認 true)
toc 【可選】顯示文章TOC(默認為設置中toc的enable配置)
toc_number 【可選】顯示toc_number(默認為設置中toc的number配置)
toc_style_simple 【可選】顯示 toc 簡潔模式
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: 标签
date: 2018-01-05 00:00:00
type: "tags"
---

分类页

  1. 前往Hexo项目根目录
  2. 输入 hexo new page categories
  3. 找到 source/categories/index.md
  4. 修改这个文件：记得添加 type: "categories"
1
2
3
4
5
---
title: 分類
date: 2018-01-05 00:00:00
type: "categories"
---

友情链接页

创建友链页面

  1. 前往Hexo项目根目录
  2. 输入 hexo new page link
  3. 找到 source/link/index.md
  4. 修改这个文件：记得添加 type: "link"
1
2
3
4
5
---
title: 友情鏈接
date: 2018-06-07 22:17:49
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: 社交分享平台

    class_name 和 class_desc 支持 html 格式书写，如不需要，也可以留空。

  • 远程拉取

    从 4.0.0 開始，支持从远程记载友情链接，远程拉取只支持 json。

    注意： 选择远程加载后，本地生成的方法会失效。

    在 source/link/index.md 的 front-matter 添加远程链接

    1
    flink_url: xxxxx

    Json 的格式

    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
    [
      {
        "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": "社交分享平台"
          }
        ]
      }
    ]

友情链接页面设置

由 2.2.0 起，友情链接界面可以由用户自己自定义，只需要在友情链接的md设置就行，以普通的Markdown格式书写。

图库

图库页面只是普通的頁面，只需要 hexo n page xxxxx 创建页面就行

然后使用标签外掛 galleryGroup，具体用法查看对应的內容。

1
2
3
4
5
<div class="gallery-group-main">
{% galleryGroup '壁紙' '收藏的一些壁紙' '/Gallery/wallpaper' https://i.loli.net/2019/11/10/T7Mu8Aod3egmC4Q.png %}
{% galleryGroup '漫威' '關於漫威的圖片' '/Gallery/marvel' https://i.loli.net/2019/12/25/8t97aVlp4hgyBGu.jpg %}
{% galleryGroup 'OH MY GIRL' '關於OH MY GIRL的圖片' '/Gallery/ohmygirl' https://i.loli.net/2019/12/25/hOqbQ3BIwa6KWpo.jpg %}
</div>
Group Image Gallery
壁紙

收藏的一些壁紙

Group Image Gallery
漫威

關於漫威的圖片

1
2
3
4
5
6
7
8
9
10
{% gallery %}
![](https://i.loli.net/2019/12/25/Fze9jchtnyJXMHN.jpg)
![](https://i.loli.net/2019/12/25/ryLVePaqkYm4TEK.jpg)
![](https://i.loli.net/2019/12/25/gEy5Zc1Ai6VuO4N.jpg)
![](https://i.loli.net/2019/12/25/d6QHbytlSYO4FBG.jpg)
![](https://i.loli.net/2019/12/25/6nepIJ1xTgufatZ.jpg)
![](https://i.loli.net/2019/12/25/E7Jvr4eIPwUNmzq.jpg)
![](https://i.loli.net/2019/12/25/mh19anwBSWIkGlH.jpg)
![](https://i.loli.net/2019/12/25/2tu9JC8ewpBFagv.jpg)
{% endgallery %}








如果想要使用 /photo/ohmygirl 这样的链接显示图片内容

可以把创建好的 ohmygirl 整个文件夹移到 photo文件夹里去

404页面

主题内置了一个简单的404页面，可在设置中开启

本地预览时，访问出错的网站是不会跳到404页面的。

如需本地预览，访问http://localhost:4000/404.html。

1
2
3
4
5
# A simple 404 page
error_404:
  enable: true
  subtitle: "頁面沒有找到"
  background:

image-20220625193408620

语言

修改站点配置文件 _config.yml

默认语言是 en

主题支持三种语言

  • default(en)
  • zh-CN (简体中文)
  • zh-TW (繁体中文)

网站资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，请修改博客根目录的 _config.yml

image-20220626225237241

导航菜单

修改 主题配置文件

1
2
3
4
5
6
7
8
9
Home: / || fas fa-home
Archives: /archives/ || fas fa-archive
Tags: /tags/ || fas fa-tags
Categories: /categories/ || fas fa-folder-open
List||fas fa-list:
  Music: /music/ || fas fa-music
  Movie: /movies/ || fas fa-video
Link: /link/ || fas fa-link
About: /about/ || fas fa-heart

必须是 /xxx/，后面||分开，然后写图标名。

如果不希望显示图标，图标名可不写。

默认子目录是展开的，如果你想要隐藏，在子目录里添加 hide 。

1
2
3
List||fas fa-list||hide:
  Music: /music/ || fas fa-music
  Movie: /movies/ || fas fa-video

注意： 导航的文字可自行更改

例如：

1
2
3
4
5
6
7
8
9
10
11
menu:
  首页: / || fas fa-home
  时间轴: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  清单||fa fa-heartbeat:
    音乐: /music/ || fas fa-music
    照片: /Gallery/ || fas fa-images
    电影: /movies/ || fas fa-video
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart

image-20220626230011905

代码

代码块中的所有功能只适用于 Hexo 自带的代码渲染

如果使用第三方的渲染器，不一定会有效

代码高亮主题

默认主题

Butterfly 支持6种代码高亮样式：

  • darker
  • pale night
  • light
  • ocean
  • mac
  • mac light

修改 主题配置文件

例如：

1
highlight_theme: light

darker

image-20220626230327987

pale night

image-20220626230352960

light

image-20220626230422907

ocean

image-20220626230439952

mac

image-20220626230457913

mac light

image-20220626230535685

自定义主题

主题从 3.0 开始，支持使用自定义的代码顔色。

1）Highlight

以使用Kimbie dark主题配色为例子

2）配置hljs为true

修改Hexo根目录下的_config.yml

1
2
3
4
5
6
highlight:
 enable: true
 line_number: true
 auto_detect: false
 tab_replace:
 hljs: true

3）配置highlight_theme为false

修改主题配置文件

1
highlight_theme: false

4）下载和修改CSS文件

在Github上找到这个CSS

在Hexo的根目录source文件夹下创立一个self文件夹，在self文件夹创建一个Kimbiedark.css文件

把Github上Kimbie dark的CSS代码复制到Kimbiedark.css去。（也可以直接从Github上下载这个CSS）

Kimbiedark.css代码如下：

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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
/*
    Name:     Kimbie (dark)
    Author:   Jan T. Sott
    License:  Creative Commons Attribution-ShareAlike 4.0 Unported License
    URL:      https://github.com/idleberg/Kimbie-highlight.js
*/

/* Kimbie Comment */
.hljs-comment,
.hljs-quote {
  color: #d6baad;
}

/* Kimbie Red */
.hljs-variable,
.hljs-template-variable,
.hljs-tag,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class,
.hljs-regexp,
.hljs-meta {
  color: #dc3958;
}

/* Kimbie Orange */
.hljs-number,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params,
.hljs-deletion,
.hljs-link {
  color: #f79a32;
}

/* Kimbie Yellow */
.hljs-title,
.hljs-section,
.hljs-attribute {
  color: #f06431;
}

/* Kimbie Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet,
.hljs-addition {
  color: #889b4a;
}

/* Kimbie Purple */
.hljs-keyword,
.hljs-selector-tag,
.hljs-function {
  color: #98676a;
}

.hljs {
  display: block;
  overflow-x: auto;
  background: #221a0f;
  color: #d3af86;
  padding: 0.5em;
}

.hljs-emphasis {
  font-style: italic;
}

.hljs-strong {
  font-weight: bold;
}

修改这个CSS文件为

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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
/*
    Name:     Kimbie (dark)
    Author:   Jan T. Sott
    License:  Creative Commons Attribution-ShareAlike 4.0 Unported License
    URL:      https://github.com/idleberg/Kimbie-highlight.js
*/

/* 新添加的内容
  ------------------------------------- 
  --hl-color                  代码框字体顔色 【必须】 (把下面.hljs的 color复製到这里来)
  --hl-bg                     代码框背景色 【必须】 (把下面.hljs的 background复製到这里来)
  --hltools-bg: #321a0f       代码框顶部工具栏背景色 【可选】(如果你关掉了 copy、lang 和 shrink,可不用配置这个）
  --hltools-color: #fff       代码框顶部工具栏字体顔色 【可选】(如果你关掉了 copy、lang 和 shrink,可不用配置这个）
  --hlnumber-bg: #221a0f      代码框行数背景色 【可选】(如果已经关掉 line_number,可以不用配置这个)
  --hlnumber-color: #fff      代码框行数字体顔色 【可选】 (如果已经关掉 line_number,可以不用配置这个)
  --hlscrollbar-bg: #d3af86   代码框滚动条顔色 【可选】（默认为主题主顔色）
  --hlexpand-bg: #d3af86      代码框底部展开背景色 【可选】(如果已经关掉 highlight_height_limit,可以不用配置这个)
*/

:root {
  --hl-color: #d3af86;
  --hl-bg: #221a0f;
  --hltools-bg: #321a0f;
  --hltools-color: #fff;
  --hlnumber-bg: #221a0f;
  --hlnumber-color: #fff;
  --hlscrollbar-bg: #d3af86;
  --hlexpand-bg: #d3af86;
}

/* Kimbie Comment */
.hljs-comment,
.hljs-quote {
  color: #d6baad;
}

/* Kimbie Red */
.hljs-variable,
.hljs-template-variable,
.hljs-tag,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class,
.hljs-regexp,
.hljs-meta {
  color: #dc3958;
}

/* Kimbie Orange */
.hljs-number,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params,
.hljs-deletion,
.hljs-link {
  color: #f79a32;
}

/* Kimbie Yellow */
.hljs-title,
.hljs-section,
.hljs-attribute {
  color: #f06431;
}

/* Kimbie Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet,
.hljs-addition {
  color: #889b4a;
}

/* Kimbie Purple */
.hljs-keyword,
.hljs-selector-tag,
.hljs-function {
  color: #98676a;
}

/* 更改的内容 把.hljs改为 #article-container figure.highlight .hljs *、
/* ------------------------------------- */
#article-container figure.highlight .hljs {
  display: block;
  overflow-x: auto;
  background: #221a0f;
  color: #d3af86;
  padding: 0.5em;
}

.hljs-emphasis {
  font-style: italic;
}

.hljs-strong {
  font-weight: bold;
}

5）引入文件

修改主题配置文件

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="/self/Kimbiedark.css">

6）运行Hexo

效果：

image-20220626231346598

代码复制

主题支持代码复制功能

修改 主题配置文件

1
highlight_copy: true

代码框展开/关闭

在默认情况下，代码框自动展开，可设置是否所有代码框都关闭状态，点击>可展开代码

  • true 全部代码框不展开，需点击>打开
  • false 代码框展开，有>点击按钮
  • none 不显示>按钮

修改 主题配置文件

1
highlight_shrink: true #代码框不展开，需点击 '>' 打开

你也可以在post/page页对应的markdown文件front-matter添加highlight_shrink来独立配置。

当主题配置文件中的 highlight_shrink 设为true时，可在front-matter添加highlight_shrink: false来单独配置文章展开代码框。

当主题配置文件中的 highlight_shrink 设为false时，可在front-matter添加highlight_shrink: true来单独配置文章收缩代码框。

代码换行

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

修改 主题配置文件

1
code_word_wrap: true

如果是使用 highlight 或 prismjs 渲染，需要找到 Hexo 配置文件_config.yml，将line_number改成false:

1
2
highlight:
  line_number: false # <- 改这里

代码高度限制

3.7.0 及以上支持

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

1
highlight_height_limit: false # unit: px

注意：

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

社交图标

Butterfly支持 font-awesome v6图标.

书写格式 图标名：url || 描述性文字

1
2
3
social:
  fab fa-github: https://github.com/xxxxx || Github
  fas fa-envelope: mailto:xxxxxx@gmail.com || Email

图标名可在这寻找

PC：

image-20220627000414481

Mobile：

image-20220627000514651

主页文章节选（自动节选和文章页description）

因为主题UI的关係，主页文章节选只支持自动节选和文章页description。

在butterfly里，有四种可供选择

  1. description： 只显示description
  2. both： 优先选择description，如果没有配置description，则显示自动节选的内容
  3. auto_excerpt：只显示自动节选
  4. false： 不显示文章内容

修改 主题配置文件

1
2
3
index_post_content:
  method: 3
  length: 500 # if you set method to 2 or 3, the length need to config

之后在front-matter里添加description以及内容即可。

顶部图

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

配置中的值：

配置 解释
index_img 主页的 top_img
default_top_img 默认的 top_img，当页面的 top_img 没有配置时，会显示 default_top_img
archive_img 归档页面的 top_img
tag_img tag 子页面 的 默认 top_img
tag_per_img tag 子页面的 top_img，可配置每个 tag 的 top_img
category_img category 子页面 的 默认 top_img
category_per_img category 子页面的 top_img，可配置每个 category 的 top_img

其它页面 （tags/categories/自建页面）和 文章页 的 top_img ，请到对应的 md 页面设置front-matter中的top_img

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

3.2.0 以下版本的配置只支持

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

tag_per_img 和 category_per_img 是 3.2.0 新增的内容，可对 tag 和 category 进行单独的配置

并不推荐为每个 tag 和每个 category 都配置不同的顶部图，因为配置太多会拖慢生成速度

1
2
3
4
5
6
7
tag_per_img：
  aplayer: https://xxxxxx.png
  android: ddddddd.png
  
category_per_img：
  随想: hdhdh.png
  推荐: ddjdjdjd.png

文章置顶

【推荐】hexo-generator-index从 2.0.0 开始，已经支持文章置顶功能。你可以直接在文章的front-matter区域里添加sticky: 1属性来把这篇文章置顶。数值越大，置顶的优先级越大。

文章封面

文章的markdown文档上,在Front-matter添加cover,并填上要显示的图片地址。
如果不配置cover,可以设置显示默认的cover.

如果不想在首页显示cover,可以设置为false

修改 主题配置文件

1
2
3
4
5
6
7
8
9
10
cover:
  # 是否显示文章封面
  index_enable: true
  aside_enable: true
  archives_enable: true
  # 封面显示的位置
  # 三个值可配置 left , right , both
  position: both
  # 当没有设置cover时，默认的封面显示
  default_cover:

当配置多张图片时,会随机选择一张作为cover.此时写法应为

1
2
3
4
default_cover:
  - https://fastly.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg.png
  - https://fastly.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg2.png
  - https://fastly.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg3.png

文章页相关配置

文章meta显示

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

修改 主题配置文件

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

主页

image-20220627002338527

文章页

image-20220627002358336

image-20220627002607218

date_format 是 3.2.0 新增的内容，配置时间显示明确时间还是相对时间

相对时间

image-20220627002650758

明确时间

image-20220627002711327

文章版权

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

修改 主题配置文件

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/

由于Hexo 4.1开始，默认对网址进行解码，以至于如果是中文网址，会被解码，可设置decode: true来显示中文网址。

如果有文章（例如：转载文章）不需要显示版权，可以在文章Front-matter单独设置

1
copyright: false

从3.0.0开始，支持对单独文章设置版权信息，可以在文章Front-matter单独设置

1
2
3
4
copyright_author: xxxx
copyright_author_href: https://xxxxxx.com
copyright_url: https://xxxxxx.com
copyright_info: 此文章版权归xxxxx所有，如有转载，请註明来自原作者

文章打赏

在你每篇文章的结尾，可以添加打赏按钮。相关二维码可以自行配置。

对于没有提供二维码的，可配置一张软件的icon图片，然后在link上添加相应的打赏链接。用户点击图片就会跳转到链接去。

link可以不写，会默认为图片的链接。

修改 主题配置文件

1
2
3
4
5
6
7
8
9
reward:
  enable: true
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: 微信
    - img: /img/alipay.jpg
      link:
      text: 支付宝

TOC

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

修改 主题配置文件

1
2
3
4
5
6
toc:
  post: true
  page: false
  number: true
  expand: false
  style_simple: false # for post
属性 解释
post 文章页是否显示 TOC
page 普通页面是否显示 TOC
number 是否显示章节数
expand 是否展开 TOC
style_simple 简洁模式（侧边栏只显示 TOC, 只对文章页有效 ）

Toc

image-20220627003350608

为特定的文章配置

在你的文章md文件的头部，加入toc_number和toc，并配置true或者false即可。

主题会优先判断文章Markdown的Front-matter是否有配置，如有，则以Front-matter的配置为準。否则，以主题配置文件中的配置为準

相关文章

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

修改 主题配置文件

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

文章锚点

开启文章锚点后，当你在文章页进行滚动时，文章链接会根据标题ID进行替换
(注意: 每替换一次，会留下一个歷史记录。所以如果一篇文章有很多锚点的话，网页的歷史记录会很多。)

修改 主题配置文件

1
2
3
# anchor
# when you scroll in post , the url will update according to header id.
anchor: true

文章过期提醒

可设置是否显示文章过期提醒，以更新时间为基準。

1
2
3
4
5
6
7
8
# Displays outdated notice for a post (文章过期提醒)
noticeOutdate:
  enable: true
  style: flat # style: simple/flat
  limit_day: 365 # When will it be shown
  position: top # position: top/bottom
  message_prev: It has been
  message_next: days since the last update, the content of the article may be outdated.

limit_day： 距离更新时间多少天才显示文章过期提醒

message_prev ： 天数之前的文字

message_next：天数之后的文字

style: flat

image-20220627003857827

style: simple

image-20220627003911970

文章编辑按钮

在文章标题旁边显示一个编辑按钮，点击会跳转到对应的链接去。

1
2
3
4
5
6
7
# Post edit
# Easily browse and edit blog source code online.
post_edit:
  enable: false
  # url: https://github.com/user-name/repo-name/edit/branch-name/subdirectory-name/
  # For example: https://github.com/jerryc127/butterfly.js.org/edit/main/source/
  url:

文章分页按钮

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

1
2
3
4
5
6
# post_pagination (分页)
# value: 1 || 2 || false
# 1: The 'next post' will link to old post
# 2: The 'next post' will link to new post
# false: disable pagination
post_pagination: false
参数 解释
post_pagination: false 关闭分页按钮
post_pagination: 1 下一篇显示的是旧文章
post_pagination: 2 下一篇显示的是新文章

image-20220627005503471

头像

修改 主题配置文件

1
2
3
avatar:
  img: /img/avatar.png
  effect: true # 头像会一直转圈

图片描述

可开启图片Figcaption描述文字显示

优先显示图片的 title 属性，然后是 alt 属性

修改 主题配置文件

1
photofigcaption: true

之后在图片底部会显示描述文字

复制相关配置

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

1
2
3
4
5
6
7
# copy settings
# copyright: Add the copyright information after copied content (复製的内容后面加上版权信息)
copy:
  enable: true
  copyright:
    enable: true
    limit_count: 50
配置 解释
enable 是否开启网站复製权限
copyright 复製的内容后面加上版权信息
enable 是否开启复製版权信息添加
limit_count 字数限制，当复製文字大于这个字数限制时，将在复製的内容后面加上版权信息

Footer设置

博客年份

since是一个来展示你站点起始时间的选项。它位于页面的最底部。

修改 主题配置文件

1
2
3
4
footer:
  owner:
    enable: true
    since: 2018

页脚自定义文本

custom_text是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等。支持 HTML。

修改 主题配置文件

1
custom_text: Hi, welcome to my <a href="https://butterfly.js.org/">blog</a>!

对于部分人需要写 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
translate:
  enable: true
  # 默认按钮显示文字(网站是简体，应设置为'default: 繁')
  default: 简
  #网站默认语言，1: 繁体中文, 2: 简体中文
  defaultEncoding: 1
  #延迟时间,若不在前, 要设定延迟翻译时间, 如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

V2.0.0 开始增加一个选项，可开启自动切换light mode 和 dark mode

autoChangeMode: 1 跟随系统而变化，不支持的浏览器/系统将按照时间晚上6点到早上6点之间切换为 dark mode

autoChangeMode: 2 只按照时间 晚上6点到早上6点之间切换为 dark mode,其余时间为light mode

autoChangeMode: false 取消自动切换

阅读模式

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

只会出现在文章页面，右下角会有閲读模式按钮。

修改 主题配置文件

1
readmode: true

按钮排序

1
2
3
4
5
6
7
# Don't modify the following settings unless you know how they work (非必要请不要修改 )
# Choose: readmode,translate,darkmode,hideAside,toc,chat,comment
# Don't repeat 不要重复
rightside_item_order:
  enable: false
  hide: # readmode,translate,darkmode,hideAside
  show: # toc,chat,comment

侧边栏设置

侧边排版

可自行决定哪个项目需要显示，可决定位置，也可以设置不显示侧边栏。

修改 主题配置文件

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
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:
      enable: true
	  icon: fab fa-github
      text: Github
      link: https://github.com/jerryc127/hexo-theme-butterfly
  card_announcement:
    enable: true
    content: This is my Blog
  card_recent_post:
    enable: true
    limit: 5 # if set 0 will show all
    sort: date # date or updated
  card_categories:
    enable: true
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
  card_tags:
    enable: true
    limit: 40 # if set 0 will show all
    color: false
  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
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true

position: left

image-20220627022729943

position: right

image-20220627022744712

card_tags color: false

image-20220627022812246

card_tags color: true

image-20220627022830512

aside button

显示隐藏侧边栏按钮

访问人数 busuanzi (UV 和 PV)

访问 busuanzi 的官方网站查看更多的介绍。

修改 主题配置文件

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

image-20220627023927580

image-20220627023951855

运行时间

网页已运行时间

修改 主题配置文件

1
2
3
4
5
6
runtimeshow:
  enable: true
  publish_date: 6/7/2018 00:00:00  
  ##网页开通时间
  #格式: 月/日/年 时间
  #也可以写成 年/月/日 时间

最新评论

3.1.0 起支持

最新评论只会在刷新时才会去读取，并不会实时变化

由于 API 有 访问次数限制，为了避免调用太多，主题默认存取期限为 10 分鐘。也就是説，调用后资料会存在 localStorage 里，10分鐘内刷新网站只会去 localStorage 读取资料。 10 分鐘期限一过，刷新页面时才会去调取 API 读取新的数据。（ 3.6.0 新增了 storage 配置，可自行配置缓存时间）

在侧边栏显示最新评论板块

修改 主题配置文件

1
2
3
4
5
6
7
# Aside widget - Newest Comments
newest_comments:
  enable: true
  sort_order: # Don't modify the setting unless you know how it works
  limit: 6
  storage: 10 # unit: mins, save data to localStorage
  avatar: true

部分配置解释：

配置 解释
limit 显示的数量
storage 设置缓存时间，单位 分鐘
avatar 是否显示头像

Demo

image-20220627024343489

自定义添加栏目

适用于 >= 3.8.0

侧边栏现在支持自定义了，可以添加自己喜欢的 widget。

可添加自己的 widget，也可以对现有的 widget 进行排序（博客资料 和 公告这两个固定，其它的能排序）

widget 排序

只需要配置 sort_order就行。（使用了 Flex 佈局的 order 属性，具体可查看 mozilla文档。简单来讲，就是配置数字来实现排序，如果不配置，则默认为 0。数字越小，排序越靠前。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
aside:
 ...
  card_recent_post:
    sort_order: # Don't modify the setting unless you know how it works
  card_categories:
    sort_order: # Don't modify the setting unless you know how it works
  card_tags:
    sort_order: # Don't modify the setting unless you know how it works
  card_archives:
    sort_order: # Don't modify the setting unless you know how it works
  card_webinfo:
    sort_order: # Don't modify the setting unless you know how it works

newest_comments:
  enable: true
  sort_order: # Don't modify the setting unless you know how it works

自定义 widget

如果你想添加自己的内容到侧边栏去，你可以自定义。

1）创建 widget.yml

在Hexo博客目录中的source/_data（如果没有 _data 文件夹，请自行创建），创建一个文件 widget.yml

2）格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
top:
  - class_name:
    id_name:
    name:
    icon:
    html:

bottom:
  - class_name:
    id_name:
    name:
    icon:
    order:
    html:

参数详解

top: 创建的 widget 会出现在非 sticky 区域（即所有页面都会显示)

bottom: 创建的 widget 会出现在 sticky 区域（除了文章页都会显示)

参数 解释
class_name 所创建的 widget 父类 class 名 （可选）
id_name 所创建的 widget 父类 id 名（可选）
name 所创建的 widget 标题
icon 所创建的 widget 图标
order 所创建的 widget 排序 （可选）
html 所创建的 widget 相关代码

image-20220627025216334

生成的 代码 为

1
2
3
4
5
6
7
8
9
<div class="card-widget 所写的 class_name" id="所写的 id_name" style="order: 所写的 order">
    <div class="item-headline">
        <i class="所写的 icon"></i>
        <span>所写的 name</span>
    </div>
    <div class="item-content">
        所写的 html
    </div>
</div>

如果你需要对添加的 widget 进行 UI 调整，请自行添加 css 到 inject 去。

3）例子

以 访客地图 为例子

  1. 获取访客地图的 html 代码

    1
    <script type="text/javascript" id="clstr_globe" src="//clustrmaps.com/globe.js?d=5V2tOKp8qAdRM-i8eu7ETTO9ugt5uKbbG-U7Yj8uMl8"></script>

  2. 创建 widget.yml

    1
    2
    3
    4
    5
    6
    7
    bottom:
        - class_name: user-map
          id_name: user-map
          name: 访客地图
          icon: fas fa-heartbeat
          order:
          html: '<script type="text/javascript" id="clstr_globe" src="//clustrmaps.com/globe.js?d=5V2tOKp8qAdRM-i8eu7ETTO9ugt5uKbbG-U7Yj8uMl8"></script>'

  3. 运行 hexo

    image-20220627025406872

标签外挂（Tag Plugins）

标籤外挂是Hexo独有的功能，并不是标準的Markdown格式。

以下的写法，只适用于Butterfly主题，用在其它主题上不会有效果，甚至可能会报错。使用前请留意

标籤外挂虽然能为主题带来一些额外的功能和UI方面的强化，但是，标籤外挂也有明显的限制，使用时请留意。

Note (Bootstrap Callout)

通用设置

移植于next主题，并进行修改。

修改 主题配置文件

1
2
3
4
5
6
7
8
9
10
11
12
note:
  # Note tag style values:
  #  - simple    bs-callout old alert style. Default.
  #  - modern    bs-callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: simple
  icons: false
  border_radius: 3
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

icons和light_bg_offset只对方法一生效

Note 标籤外挂有两种用法

用法1

1
2
3
{% note [class] [no-icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}
名称 用法
class 【可选】标识，不同的标识有不同的配色
（ default / primary / success / info / warning / danger ）
no-icon 【可选】不显示 icon
style 【可选】可以覆盖配置中的 style
（simple/modern/flat/disabled）

simple

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
{% note simple %}
默认 提示块标籤
{% endnote %}

{% note default simple %}
default 提示块标籤
{% endnote %}

{% note primary simple %}
primary 提示块标籤
{% endnote %}

{% note success simple %}
success 提示块标籤
{% endnote %}

{% note info simple %}
info 提示块标籤
{% endnote %}

{% note warning simple %}
warning 提示块标籤
{% endnote %}

{% note danger simple %}
danger 提示块标籤
{% endnote %}。

image-20220627030634025

modern

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
{% note modern %}
默认 提示块标籤
{% endnote %}

{% note default modern %}
default 提示块标籤
{% endnote %}

{% note primary modern %}
primary 提示块标籤
{% endnote %}

{% note success modern %}
success 提示块标籤
{% endnote %}

{% note info modern %}
info 提示块标籤
{% endnote %}

{% note warning modern %}
warning 提示块标籤
{% endnote %}

{% note danger modern %}
danger 提示块标籤
{% endnote %}

image-20220627030710511

flat

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
{% note flat %}
默认 提示块标籤
{% endnote %}

{% note default flat %}
default 提示块标籤
{% endnote %}

{% note primary flat %}
primary 提示块标籤
{% endnote %}

{% note success flat %}
success 提示块标籤
{% endnote %}

{% note info flat %}
info 提示块标籤
{% endnote %}

{% note warning flat %}
warning 提示块标籤
{% endnote %}

{% note danger flat %}
danger 提示块标籤
{% endnote %}

image-20220627030740654

disabled

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
{% note disabled %}
默认 提示块标籤
{% endnote %}

{% note default disabled %}
default 提示块标籤
{% endnote %}

{% note primary disabled %}
primary 提示块标籤
{% endnote %}

{% note success disabled %}
success 提示块标籤
{% endnote %}

{% note info disabled %}
info 提示块标籤
{% endnote %}

{% note warning disabled %}
warning 提示块标籤
{% endnote %}

{% note danger disabled %}
danger 提示块标籤
{% endnote %}

image-20220627030812402

no-icon

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
{% note no-icon %}
默认 提示块标籤
{% endnote %}

{% note default no-icon %}
default 提示块标籤
{% endnote %}

{% note primary no-icon %}
primary 提示块标籤
{% endnote %}

{% note success no-icon %}
success 提示块标籤
{% endnote %}

{% note info no-icon %}
info 提示块标籤
{% endnote %}

{% note warning no-icon %}
warning 提示块标籤
{% endnote %}

{% note danger no-icon %}
danger 提示块标籤
{% endnote %}

image-20220627030851686

用法2（自定义 icon）

3.2.0 以上版本支

1
2
3
{% note [color] [icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}
名称 用法
color 【可选】顔色
(default / blue / pink / red / purple / orange / green)
icon 【可选】可配置自定义 icon (只支持 fontawesome 图标, 也可以配置 no-icon )
style 【可选】可以覆盖配置中的 style
（simple/modern/flat/disabled）

simple

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' simple %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' simple %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' simple %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' simple%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' simple %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' simple %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' simple %}
前端最讨厌的浏览器
{% endnote %}

image-20220627031118319

modern

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' modern %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' modern %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' modern %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' modern%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' modern %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' modern %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' modern %}
前端最讨厌的浏览器
{% endnote %}

image-20220627031141566

flat

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' flat %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' flat %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' flat %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' flat%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' flat %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' flat %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' flat %}
前端最讨厌的浏览器
{% endnote %}

image-20220627031302961

disabled

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' disabled %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' disabled %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' disabled %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' disabled %}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' disabled %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' disabled %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' disabled %}
前端最讨厌的浏览器
{% endnote %}

image-20220627031326429

no-icon

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note no-icon %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue no-icon %}
2021年快到了....
{% endnote %}
{% note pink no-icon %}
小心开车 安全至上
{% endnote %}
{% note red no-icon %}
这是三片呢？还是四片？
{% endnote %}
{% note orange no-icon %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple no-icon %}
剪刀石头布
{% endnote %}
{% note green no-icon %}
前端最讨厌的浏览器
{% endnote %}

image-20220627031348326

Gallery相册图库

2.2.0以上提供

一个图库集合。

写法

1
2
3
4
5
<div class="gallery-group-main">
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
</div>
  • name：图库名字
  • description：图库描述
  • link：连接到对应相册的地址
  • img-url：图库封面的地址

在图库目录里有例子

Gallery相册

2.0.0以上提供

区别于旧版的Gallery相册,新的Gallery相册会自动根据图片长度进行排版，书写也更加方便，与markdown格式一样。可根据需要插入到相应的md。

写法

1
2
3
{% gallery %}
markdown 图片格式
{% endgallery %}

在图库目录里有例子

tag-hide

2.2.0以上提供

请注意，tag-hide内的标签外挂content内都不建议有h1 - h6 等标题。因为Toc会把隐藏内容标题也显示出来，而且当滚动屏幕时，如果隐藏内容没有显示出来，会导致Toc的滚动出现异常。

如果你想把一些文字、内容隐藏起来，并提供按钮让用户点击显示。可以使用这个标籤外挂。

Inline

inline 在文本里面添加按钮隐藏内容，只限文字

( content不能包含英文逗号，可用&sbquo;)

1
{% hideInline content,display,bg,color %}

  • content: 文本内容

  • display: 按钮显示的文字(可选)

  • bg: 按钮的背景颜色(可选)

  • color: 按钮文字的颜色(可选)

Demo

1
2
3
哪个英文字母最酷？ {% hideInline 因为西装裤(C装酷),查看答案,#FF7242,#fff %}

门里站着一个人? {% hideInline 闪 %}

哪个英文字母最酷？ 因为西装裤(C装酷)

门里站着一个人? 闪

Block

block独立的block隐藏内容，可以隐藏很多内容，包括图片，代码块等等

( display 不能包含英文逗号，可用&sbquo;)

1
2
3
{% hideBlock display,bg,color %}
content
{% endhideBlock %}
  • content: 文本内容
  • display: 按钮显示的文字(可选)
  • bg: 按钮的背景颜色(可选)
  • color: 按钮文字的颜色(可选)

Demo

1
2
3
4
查看答案
{% hideBlock 查看答案 %}
傻子，怎么可能有答案
{% endhideBlock %}

查看答案

傻子，怎么可能有答案

Toggle

2.3.0以上支持

如果你需要展示的内容太多，可以把它隐藏在收缩框里，需要时再把它展开。

( display 不能包含英文逗号，可用&sbquo;)

1
2
3
{% hideToggle display,bg,color %}
content
{% endhideToggle %}

Demo

1
2
3
4
5
6
7
8
9
10
{% hideToggle Butterfly安装方法 %}
在你的博客根目录里

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

如果想要安装比较新的dev分支，可以

git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

{% endhideToggle %}
Butterfly安装方法

在你的博客根目录里

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

如果想要安装比较新的dev分支，可以

git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

mermaid

使用mermaid标籤可以绘製Flowchart（流程图）、Sequence diagram（时序图 ）、Class Diagram（类别图）、State Diagram（状态图）、Gantt（甘特图）和Pie Chart（圆形图），具体可以查看mermaid文档

修改 主题配置文件

1
2
3
4
5
6
7
8
# mermaid
# see https://github.com/mermaid-js/mermaid
mermaid:
  enable: true
  # built-in themes: default/forest/dark/neutral
  theme:
    light: default
    dark: dark

写法：

1
2
3
{% mermaid %}
内容
{% endmermaid %}

例如：

1
2
3
4
5
6
7
8
{% mermaid %}
pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5
{% endmermaid %}

Tabs

移植于next主题

使用方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% tabs Unique name, [index] %}
<!-- tab [Tab caption] [@icon] -->
Any content (support inline tags too).
<!-- endtab -->
{% endtabs %}

Unique name   : Unique name of tabs block tag without comma.
                Will be used in #id's as prefix for each tab with their index numbers.
                If there are whitespaces in name, for generate #id all whitespaces will replaced by dashes.
                Only for current url of post/page must be unique!
[index]       : Index number of active tab.
                If not specified, first tab (1) will be selected.
                If index is -1, no tab will be selected. It's will be something like spoiler.
                Optional parameter.
[Tab caption] : Caption of current tab.
                If not caption specified, unique name with tab index suffix will be used as caption of tab.
                If not caption specified, but specified icon, caption will empty.
                Optional parameter.
[@icon]       : FontAwesome icon name (full-name, look like 'fas fa-font')
                Can be specified with or without space; e.g. 'Tab caption @icon' similar to 'Tab caption@icon'.
                Optional parameter.

Demo 1 - 预设选择第一个【默认】

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

This is Tab 1.

This is Tab 2.

This is Tab 3.

Demo 2 - 预设选择tabs

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test2, 3 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

This is Tab 1.

This is Tab 2.

This is Tab 3.

Demo 3 - 没有预设值

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test3, -1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

This is Tab 1.

This is Tab 2.

This is Tab 3.

Demo 4 - 自定义Tab名 + 只有icon + icon和Tab名

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test4 %}
<!-- tab 第一个Tab -->
**tab名字为第一个Tab**
<!-- endtab -->

<!-- tab @fab fa-apple-pay -->
**只有图标 没有Tab名字**
<!-- endtab -->

<!-- tab 炸弹@fas fa-bomb -->
**名字+icon**
<!-- endtab -->
{% endtabs %}

tab名字为第一个Tab

只有图标 没有Tab名字

名字+icon

Button

3.0以上适用

使用方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{% btn [url],[text],[icon],[color] [style] [layout] [position] [size] %}

[url]         : 链接
[text]        : 按钮文字
[icon]        : [可选] 图标
[color]       : [可选] 按钮背景顔色(默认style时）
                      按钮字体和边框顔色(outline时)
                      default/blue/pink/red/purple/orange/green
[style]       : [可选] 按钮样式 默认实心
                      outline/留空
[layout]      : [可选] 按钮佈局 默认为line
                      block/留空
[position]    : [可选] 按钮位置 前提是设置了layout为block 默认为左边
                      center/right/留空
[size]        : [可选] 按钮大小
                      larger/留空

Demo

1
2
3
4
5
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,,outline %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,larger %}

This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly

1
2
3
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block center larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block right outline larger %}
Butterfly Butterfly Butterfly

more than one button in center

1
2
3
4
5
6
7
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,blue larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,pink larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,red larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,purple larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,orange larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,green larger %}
Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly 
1
2
3
4
5
6
7
8
9
<div class="btn-center">
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline blue larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline pink larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline red larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline purple larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline orange larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline green larger %}
</div>
Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly

inlineImg

主题中的图片都是默认以块级元素显示，如果你想以内联元素显示，可以使用这个标签外挂。

1
2
3
4
{% inlineImg [src] [height] %}

[src]      :    图片链接
[height]   ：   图片高度限制【可选】

Demo

1
2
3
4
5
你看我长得漂亮不

![](https://i.loli.net/2021/03/19/2P6ivUGsdaEXSFI.png)

我觉得很漂亮 {% inlineImg https://i.loli.net/2021/03/19/5M4jUB3ynq7ePgw.png 150px %}

你看我长得漂亮不

我觉得很漂亮

label

3.7.5 及以上版本适用

高亮所需的文字

1
{% label text color %}
参数 解释
text 【可选】背景颜色，默认为 default
color default/blue/pink/red/purple/orange/green

Demo

1
2
臣亮言：{% label 先帝 %}创业未半，而{% label 中道崩殂 blue %}。今天下三分，{% label 益州疲敝 pink %}，此诚{% label 危急存亡之秋 red %}也！然侍衞之臣，不懈于内；{% label 忠志之士 purple %}，忘身于外者，盖追先帝之殊遇，欲报之于陛下也。诚宜开张圣听，以光先帝遗德，恢弘志士之气；不宜妄自菲薄，引喻失义，以塞忠谏之路也。
宫中、府中，俱为一体；陟罚臧否，不宜异同。若有{% label 作奸 orange %}、{% label 犯科 green %}，及为忠善者，宜付有司，论其刑赏，以昭陛下平明之治；不宜偏私，使内外异法也。

臣亮言：先帝 创业未半，而中道崩殂 。今天下三分，益州疲敝 ，此诚危急存亡之秋 也！然侍衞之臣，不懈于内；忠志之士 ，忘身于外者，盖追先帝之殊遇，欲报之于陛下也。诚宜开张圣听，以光先帝遗德，恢弘志士之气；不宜妄自菲薄，引喻失义，以塞忠谏之路也。
宫中、府中，俱为一体；陟罚臧否，不宜异同。若有作奸 、犯科 ，及为忠善者，宜付有司，论其刑赏，以昭陛下平明之治；不宜偏私，使内外异法也。

timeline

4.0.0 以上支持

1
2
3
4
5
6
7
8
{% timeline title,color %}
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
{% endtimeline %}
参数 解释
title 标题/时间线
color timeline 颜色
default(留空) / blue / pink / red / purple / orange / green

Demo

1
2
3
4
5
{% timeline 2022 %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,blue %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,pink %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,red %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,purple %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,orange %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

1
2
3
4
5
{% timeline 2022,green %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2022

01-02

这是测试页面

4.1.0 支持

可在任何界面插入类似友情链接列表效果

内容格式与友情链接界面一样，支持 yml 格式

1
2
3
{% flink %}
xxxxxx
{% endflink %}

Demo

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
{% flink %}
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: JerryC
      link: https://jerryc.me/
      avatar: https://jerryc.me/img/avatar.png
      descr: 今日事,今日毕
    - 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: 社交分享平台
{% endflink %}
友情链接
那些人，那些事
JerryC
JerryC
今日事,今日毕
Hexo
Hexo
快速、简单且强大的网誌框架
网站
值得推荐的网站
Youtube
Youtube
视频网站
Weibo
Weibo
中国最大社交分享平台
Twitter
Twitter
社交分享平台

评论

从3.0.0开始，开启评论需要在comments-use中填写你需要的评论。

支持双评论显示，只需要配置两个评论（第一个为默认显示）

1
2
3
4
5
6
7
8
9
10
comments:
  # Up to two comments system, the first will be shown as default
  # Choose: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo
  use: Valine,Disqus
  text: true # Display the comment name next to the button
  # lazyload: The comment system will be load when comment element enters the browser's viewport.
  # If you set it to true, the comment count will be invalid
  lazyload: true
  count: true # Display comment count in top_img
  card_post_count: false # Display comment count in Home Page
参数 解释
use 使用的评论（请注意，最多支持两个，如果不需要请留空）
注意：双评论不能是 Disqus 和 Disqusjs 一起，由于其共用同一个 ID，会出错
text 是否显示评论服务商的名字
lazyload 是否为评论开启lazyload，开启后，只有滚动到评论位置时才会加载评论所需要的资源（开启 lazyload 后，评论数将不显示）
count 是否在文章顶部显示评论数
livere、Giscus 和 utterances 不支持评论数显示
card_post_count 是否在首页文章卡片显示评论数
gitalk、livere 、Giscus 和 utterances 不支持评论数显示

单评论

image-20220627125805692

双评论

image-20220627125854914

显示text

image-20220627125957761

不显示text

image-20220627130029674

註册 disqus，配置你自己的 disqus，然后在Butterfly里开启它。

修改 主题配置文件

1
2
disqus:
  shortname:

image-20220627130211488

与Disqus一样，但由于Disqus在中国大陆无法访问， 使用Disqusjs可以在无法访问Disqus时显示评论。具体可参考Disqusjs。

修改 主题配置文件

1
2
3
4
disqusjs:
  shortname:
  apikey:
  option:

当无法访问 Disqus 时，会显示

image-20220627130325680

註册 来必力，配置你自己的来必力设置，然后在Butterfly里开启它。

修改 主题配置文件

1
2
livere:
  uid:

laibili 的 uid 你能在这里找到:

image-20220627130517360

image-20220627130530336

遵循 gitalk 的指示去获取你的 github Oauth 应用的 client id 和 secret 值。以及查看它的相关配置説明。

然后修改 主题配置文件:

1
2
3
4
5
6
7
gitalk:
  client_id:
  client_secret:
  repo:
  owner:
  admin:
  option:

image-20220627130647094

遵循 Valine 的指示去配置你的 LeanCloud 应用。以及查看相应的配置説明。

然后修改 主题配置文件:

1
2
3
4
5
6
7
8
valine:
  appId: # leancloud application app id
  appKey: # leancloud application app key
  avatar: monsterid # gravatar style https://valine.js.org/#/avatar
  serverURLs: # This configuration is suitable for domestic custom domain name users, overseas version will be automatically detected (no need to manually fill in)
  bg: # valine background
  visitor: false
  option:

开启 visitor 后，文章页的访问人数将改为 Valine 提供，而不是 不蒜子

Valine于 v1.4.5 开始支持自定义表情，如果你需要自行配置，请在emojiCDN配置表情 CDN。

同时在Hexo 工作目录下的source/_data/创建一个json文件valine.json,等同于 Valine 需要配置的emojiMaps，valine.json配置方式可参考如下

>

valine.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{ 
"tv_doge": "6ea59c827c414b4a2955fe79e0f6fd3dcd515e24.png",
"tv_亲亲": "a8111ad55953ef5e3be3327ef94eb4a39d535d06.png",
"tv_偷笑": "bb690d4107620f1c15cff29509db529a73aee261.png",
"tv_再见": "180129b8ea851044ce71caf55cc8ce44bd4a4fc8.png",
"tv_冷漠": "b9cbc755c2b3ee43be07ca13de84e5b699a3f101.png",
"tv_发怒": "34ba3cd204d5b05fec70ce08fa9fa0dd612409ff.png",
"tv_发财": "34db290afd2963723c6eb3c4560667db7253a21a.png",
"tv_可爱": "9e55fd9b500ac4b96613539f1ce2f9499e314ed9.png",
"tv_吐血": "09dd16a7aa59b77baa1155d47484409624470c77.png",
"tv_呆": "fe1179ebaa191569b0d31cecafe7a2cd1c951c9d.png",
"tv_呕吐": "9f996894a39e282ccf5e66856af49483f81870f3.png",
"tv_困": "241ee304e44c0af029adceb294399391e4737ef2.png",
"tv_坏笑": "1f0b87f731a671079842116e0991c91c2c88645a.png",
"tv_大佬": "093c1e2c490161aca397afc45573c877cdead616.png",
"tv_大哭": "23269aeb35f99daee28dda129676f6e9ea87934f.png",
"tv_委屈": "d04dba7b5465779e9755d2ab6f0a897b9b33bb77.png",
"tv_害羞": "a37683fb5642fa3ddfc7f4e5525fd13e42a2bdb1.png",
"tv_尴尬": "7cfa62dafc59798a3d3fb262d421eeeff166cfa4.png",
"tv_微笑": "70dc5c7b56f93eb61bddba11e28fb1d18fddcd4c.png",
"tv_思考": "90cf159733e558137ed20aa04d09964436f618a1.png",
"tv_惊吓": "0d15c7e2ee58e935adc6a7193ee042388adc22af.png"
}

image-20220627143833183

Waline - 一款从 Valine 衍生的带后端评论系统。可以将 Waline 等价成 With backend Valine。

具体配置可参考 waline 文档

然后修改 主题配置文件:

1
2
3
4
5
waline:
  serverURL: # Waline server address url
  bg: # waline background
  pageview: false
  option:

开启 pageview 后，文章页的访问人数将改为 Waline 提供，而不是 不蒜子

image-20220627144129225

与Gitalk一样，基于 GitHub issues 的评论工具。相对于Gitalk,其相对需要权限较少。具体配置可参考Utterances。

修改 主题配置文件:

1
2
3
4
5
6
7
utterances:
  repo:
  # 可选 pathname/url/title/og:title
  issue_term: pathname
  # 可选 github-light/github-dark/github-dark-orange/icy-dark/dark-blue/photon-dark
  light_theme: github-light
  dark_theme: photon-dark

image-20220627144218988

Facebook Comments是Facebook提供的评论插件，需要登陆Facebook才可评论。

修改 主题配置文件

1
2
3
4
5
6
7
8
# Facebook Comments Plugin
# https://developers.facebook.com/docs/plugins/comments/
facebook_comments:
  app_id: 
  user_id: # optional
  pageSize: 10 # The number of comments to show
  order_by: social # social/time/reverse_time
  lang: en_US # Language en_US/zh_CN/zh_TW and so on

image-20220627144313471

Twikoo 是一个简洁、安全、无后端的静态网站评论系统，基于腾讯云开发。

具体如何配置评论，请查看 Twikoo文档

你只需要把获取到的 环境ID (envId) 填写到配置上去就行

具体教程

修改 主题配置文件

1
2
3
4
5
twikoo:
  envId:
  region:
  visitor: false
  option:
参数 解释
envId 环境 ID
region 环境地域，默认为 ap-shanghai，如果您的环境地域不是上海，需传此参数
visitor 是否显示文章閲读数
option 可选配置

开启 visitor 后，文章页的访问人数将改为 Twikoo 提供，而不是 不蒜子

image-20220627144600453

一个基于 GitHub Discussions 的评论

1
2
3
4
5
6
7
8
9
10
# Giscus
# https://giscus.app/
giscus:
  repo:
  repo_id:
  category_id:
  theme:
    light: light
    dark: dark
  option:

具体配置的意思，请参考 Giscus 的文档

image-20220627144650154

在线聊天

从3.0开始，Butterfly主题内置了多种在綫聊天工具。你可以选择开启一种，方便你与访客的交流。

这些工具都提供了一个按钮可以打开/关闭聊天窗口。
主题也提供了一个集合主题特色的按钮来替换这些工具本身的按钮，这个聊天按钮将会出现在右下角里。
你只需要把chat_btn打开就行。

修改 主题配置文件

1
2
3
# Chat Button [recommend]
# It will create a button in the bottom right corner of website, and hide the origin button
chat_btn: true

image-20220627153456483

为了不影响访客的体验，主题提供一个chat_hide_show配置
设为true后，使用工具提供的按钮时，只有向上滚动才会显示聊天按钮，向下滚动时会隐藏按钮。

修改 主题配置文件

1
2
# The origin chat button is displayed when scrolling up, and the button is hidden when scrolling down
chat_hide_show: true

如果使用工具自带的聊天按钮，按钮位置可能会遮挡右下角图标，请配置rightside-bottom调正右下角图标位置

配置chatra,需要知道Public key

打开chatra并註册账号。
你可以在Preferences中找到Public key

image-20220627153838554

修改 主题配置文件

1
2
3
4
5
# chatra
# https://chatra.io/
chatra:
  enable: true
  id: xxxxxxxx

chatra的样式可以Chat Widget自行配置

image-20220627153946325

Demo

image-20220627154017666

配置tidio,需要知道Public key

打开tidio并註册账号。
你可以在Preferences > Developer中找到Public key

image-20220627154124856

修改 主题配置文件

1
2
3
4
5
# tidio
# https://www.tidio.com/
tidio:
  enable: true
  public_key: XXXX

tidio的样式你可以Channels自行配置

image-20220627154223299

Demo

image-20220627154254223

打开daovoice和註册帐号
找到你的app id

image-20220627154331644

修改 主题配置文件

1
2
3
4
5
# daovoice
# http://daovoice.io/
daovoice:
  enable: true
  app_id: xxxxx

可在聊天设置里配置聊天按钮等样式

image-20220627154428418

Demo

image-20220627154448914

打开Gitter和註册账号
创建一个community或者room,复製名称到设置去

image-20220627154528122

修改 主题配置文件

1
2
3
4
5
# gitter
# https://gitter.im/
gitter:
  enable: true
  room:

Demo

image-20220627154607278

打开crisp并註册帐号

找到需要的网站ID

1
2
3
4
5
# crisp
# https://crisp.chat/en/
crisp:
  enable: false
  website_id: xxxxxxxx

image-20220627154655518

image-20220627154708831

分享

只能选择一个分享服务商

访问 AddThis 官网

找到你的 pub-id

image-20220627155102408

修改 主题配置文件

1
2
3
addThis:
  enable: true # or false
  pubid: 你的pub-id

如果你不知道 sharejs，看看它的説明。

修改 主题配置文件

1
2
3
sharejs:
  enable: true
  sites: facebook,twitter,wechat,weibo,qq  #想要显示的内容

image-20220627155256914

可以到addtoany查看使用説明

1
2
3
addtoany:
  enable: true
  item: facebook,twitter,wechat,sina_weibo,facebook_messenger,email,copy_link

image-20220627155327015

搜索系统

记得运行 hexo clean

  1. 你需要安装 hexo-algolia或 hexo-algoliasearch. 根据它们的説明文档去做相应的配置。

  2. 修改 主题配置文件

1
2
3
4
algolia_search:
  enable: true
  hits:
    per_page: 6

记得运行 hexo clean

  1. 你需要安装npm install hexo-generator-searchdb --save

  2. 修改根目录下的_config.yml

    1
    2
    3
    4
    5
    6
    7
    # 没有则添加
    search:
      path: search.xml
      field: post
      format: html
      limit: 10000
      content: true

  3. 修改 主题配置文件

1
2
3
4
local_search:
  enable: true
  preload: false
  CDN:
参数 解释
enable 是否开启本地搜索
preload 预加载，开启后，进入网页后会自动加载搜索文件。关闭时，只有点击搜索按钮后，才会加载搜索文件
CDN 搜索文件的 CDN 地址（默认使用的本地链接）

网站验证

如果需要搜索引擎收录网站，可能需要登录对应搜索引擎的管理平台进行提交。
各自的验证码可从各自管理平台拿到

修改 主题配置文件

1
2
3
4
5
site_verification:
  # - name: google_site_verification
  #   content: xxxxxx
  # - name: baidu_site_verification
  #   content: xxxxxxx

分析统计

  1. 登录百度统计的官方网站
  2. 找到你百度统计的统计代码

image-20220627161143667

​ 3. 修改 主题配置文件

1
baidu_analytics: 你的代码
  1. 登录谷歌分析的官方网站
  2. 找到你的谷歌分析的跟踪 ID

image-20220627161312529

​ 3. 修改 主题配置文件

1
google_analytics: 你的代码 # 通常以`UA-`打头
  1. 登录CNZZ分析的官方网站
  2. 找到 站点设置 - 获取代码
  3. 找到你的 web_id

image-20220627161414892

​ 4. 修改 主题配置文件

1
cnzz_analytics:
  1. 登录 Cloudflare 分析的官方网站
  2. 找到 JavaScript 程式码片段
  3. 找到你的 token

image-20220627161553780

​ 4. 修改 主题配置文件

1
2
3
# Cloudflare Analytics
# https://www.cloudflare.com/zh-tw/web-analytics/
cloudflare_analytics:
  1. 登录 Clarity 的官方网站

  2. 创建 PROJECT

  3. 找到你的 ID

image-20220627161742245

​ 4. 修改 主题配置文件

1
2
3
# Microsoft Clarity
# https://clarity.microsoft.com/
microsoft_clarity:

广告

主题已集成谷歌广告（自动广告）

修改 主题配置文件

1
2
3
4
5
6
google_adsense:
  enable: true
  auto_ads: true
  js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
  client: # 填入个人识别码
  enable_page_level_ads: true

image-20220627161938754

主题预留了三个位置可供插入广告，分别为主页文章(每三篇文章出现广告)/aside公告之后/文章页打赏之后。
把html代码填写到对应的位置

修改 主题配置文件

1
2
3
4
ad:
  index:
  aside:
  post:

例如：

1
index: <ins class="adsbygoogle" style="display:block" data-ad-format="fluid" data-ad-layout-key="xxxxxxxxxxxx" data-ad-client="ca-pub-xxxxxxxxxx" data-ad-slot="xxxxxxxxxx"></ins><script>(adsbygoogle=window.adsbygoogle||[]).push({})</script>

image-20220627162109453

image-20220627162131156

Math数学

不要在标题里使用 mathjax 语法，toc 目录不一定能正确显示 mathjax，可能显示 mathjax 代码

建议使用 KaTex 获得更好的效果，下文有介绍！

修改 主题配置文件

1
2
3
4
5
mathjax:
  enable: true
  # true 表示每一页都加载mathjax.js
  # false 需要时加载，须在使用的Markdown Front-matter 加上 mathjax: true
  per_page: false

如果 per_page 设为 true,则每一页都会加载 Mathjax 服务。设为 false，则需要在文章 Front-matter 添加 mathjax: true,对应的文章才会加载 Mathjax 服务。

然后你需要修改一下默认的 markdown 渲染引擎来实现 MathJax 的效果。

查看: hexo-renderer-kramed

以下操作在你 hexo 博客的目录下 (不是 Butterfly 的目录):

  1. 安装插件

    1
    2
    npm uninstall hexo-renderer-marked --save
    npm install hexo-renderer-kramed --save

  2. 配置 hexo 根目录的配置文件

    1
    2
    3
    4
    5
    6
    7
    8
    kramed:
      gfm: true
      pedantic: false
      sanitize: false
      tables: true
      breaks: true
      smartLists: true
      smartypants: true

效果：

image-20220627165514499

不要在标题里使用 KaTeX 语法，toc 目录不能正确显示 KaTeX。

首先禁用MathJax（如果你配置过 MathJax 的话），然后修改你的主题配置文件以便加载katex.min.css:

1
2
3
4
5
6
katex:
  enable: true
  # true 表示每一页都加载katex.js
  # false 需要时加载，须在使用的Markdown Front-matter 加上 katex: true
  per_page: false
  hide_scrollbar: true

你不需要添加 katex.min.js 来渲染数学方程。相应的你需要卸载你之前的 hexo 的 markdown 渲染器，然后安装其它插件。

卸载掉 marked 插件，安装 hexo-renderer-markdown-it


1
2
3
4
5
npm un hexo-renderer-marked --save # 如果有安装这个的话，卸载
npm un hexo-renderer-kramed --save # 如果有安装这个的话，卸载

npm i hexo-renderer-markdown-it --save # 需要安装这个渲染插件
npm install @neilsustc/markdown-it-katex --save #需要安装这个katex插件

在 hexo 的根目录的 _config.yml 中配置

1
2
3
4
5
6
markdown:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      options:
        strict: false

如需配置其它参数，请参考 katex 官网

注意，此方法生成的 katex 没有斜体

卸载掉 marked 插件，然后安装新的hexo-renderer-markdown-it-plus:

1
2
3
4
5
6
7
8
9
10
11
# 替换 `hexo-renderer-kramed` 或者 `hexo-renderer-marked` 等hexo的markdown渲染器
# 你可以在你的package.json里找到hexo的markdwon渲染器，并将其卸载
npm un hexo-renderer-marked --save

# or

npm un hexo-renderer-kramed --save


# 然后安装 `hexo-renderer-markdown-it-plus`
npm i @upupming/hexo-renderer-markdown-it-plus --save

注意到 hexo-renderer-markdown-it-plus已经无人持续维护, 所以我们使用 @upupming/hexo-renderer-markdown-it-plus。 这份 fork 的代码使用了 @neilsustc/markdown-it-katex同时它也是 VSCode 的插件 Markdown All in One所使用的, 所以我们可以获得最新的 KaTex 功能例如 \tag{}。

你还可以通过 @neilsustc/markdown-it-katex控制 KaTeX 的设置，所有可配置的选项参见 https://katex.org/docs/options.html。 比如你想要禁用掉 KaTeX 在命令行上输出的宂长的警告信息，你可以在根目录的 _config.yml 中使用下面的配置将 strict 设置为 false:

1
2
3
4
5
6
7
markdown_it_plus:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      enable: true
      options:
        strict: false

因为 KaTeX 更快更轻量，因此没有 MathJax 的功能多（比如右键菜单）。为那些使用 MathJax 的用户，主题也内置了 katex 的 复製 功能。

美化/特效

自定义主题颜色

可以修改大部分UI颜色

修改 主题配置文件，比如：

颜色值必须被双引号包裹，就像”#000”而不是#000。否则将会在构建的时候报错！

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
theme_color:
  enable: true
  main: "#49B1F5"
  paginator: "#00c4b6"
  button_hover: "#FF7242"
  text_selection: "#00c4b6"
  link_color: "#99a9bf"
  meta_color: "#858585"
  hr_color: "#A4D8FA"
  code_foreground: "#F47466"
  code_background: "rgba(27, 31, 35, .05)"
  toc_color: "#00c4b6"
  blockquote_padding_color: "#49b1f5"
  blockquote_background_color: "#49b1f5"
  scrollbar_color: "#49b1f5"

网站背景

默认显示白色，可设置图片或者颜色

修改 主题配置文件

1
2
3
4
# 图片格式 url(http://xxxxxx.com/xxx.jpg)
# 颜色（HEX值/RGB值/顔色单词/渐变色)
# 留空 不显示背景
background:

留意: 如果你的网站根目录不是’/‘,使用本地图片时，需加上你的根目录。

例如：网站是 https://yoursite.com/blog,引用一张img/xx.png图片，则设置background为 `url(/blog/img/xx.png)

background: url(https://i.loli.net/2019/09/09/5oDRkWVKctx2b6A.png)

image-20220627172030986

footer背景

修改 主题配置文件

1
2
# footer是否显示图片背景(与top_img一致)
footer_bg: true
配置的值 效果
留空/false 显示默认的顔色
img链接 图片的链接，显示所配置的图片
顔色(
HEX值 - #0000FF
RGB值 - rgb(0,0,255)
顔色单词 - orange
渐变色 - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%)
）		 对应的顔色
true 显示跟 top_img 一样

true

image-20220627172220808

打字效果

打字效果activate-power-mode

修改 主题配置文件

1
2
3
4
5
6
7
# Typewriter Effect (打字效果)
# https://github.com/disjukr/activate-power-mode
activate_power_mode:
  enable: true
  colorful: true # open particle animation (冒光特效)
  shake: true #  open shake (抖动特效)
  mobile: false

背景特效

好看的綵带背景，可设置每次刷新更换綵带，或者每次点击更换綵带
修改 主题配置文件

1
2
3
4
5
6
7
canvas_ribbon:
  enable: false
  size: 150
  alpha: 0.6
  zIndex: -1
  click_to_change: false  #设置是否每次点击都更换綵带
  mobile: false # false 手机端不显示 true 手机端显示

相关配置可查看canvas_ribbon

好看的綵带背景，会飘动
修改 主题配置文件

1
2
3
canvas_fluttering_ribbon:
  enable: true
  mobile: false # false 手机端不显示 true 手机端显示

修改 主题配置文件

1
2
3
4
5
6
7
canvas_nest:
  enable: true
  color: '0,0,255' #color of lines, default: '0,0,0'; RGB values: (R,G,B).(note: use ',' to separate.)
  opacity: 0.7 # the opacity of line (0~1), default: 0.5.
  zIndex: -1 # z-index property of the background, default: -1.
  count: 99 # the number of lines, default: 99.
  mobile: false # false 手机端不显示 true 手机端显示

鼠标点击效果

zIndex建议只在-1和9999上选
-1 代表烟火效果在底部
9999 代表烟火效果在前面

修改 主题配置文件

1
2
3
4
fireworks:
  enable: true
  zIndex: 9999 # -1 or 9999
  mobile: false

修改 主题配置文件

1
2
3
4
# 点击出现爱心
click_heart:
  enable: true
  mobile: false

修改 主题配置文件

1
2
3
4
5
6
7
8
9
10
# 点击出现文字，文字可自行修改
ClickShowText:
  enable: false
  text:
    - I
    - LOVE
    - YOU
  fontSize: 15px
  random: false # 文字随机显示
  mobile: false

页面美化

会改变ol、ul、h1-h5的样式

field配置生效的区域

  • post 只在文章页生效
  • site 在全站生效

修改 主题配置文件

1
2
3
4
5
6
# 美化页面显示
beautify:
  enable: true
  field: site # site/post
  title-prefix-icon: '\f0c1'
  title-prefix-icon-color: "#F47466"

title-prefix-icon填写的是fontawesome的icon的Unicode数。

未开启美化

image-20220627173635151

开启美化

image-20220627173652960

自定义字体和字体大小

全局字体

可自行设置字体的font-family
如不需要配置，请留空

修改 主题配置文件

1
2
3
4
5
6
7
# Global font settings
# Don't modify the following settings unless you know how they work (非必要不要修改)
font:
  global-font-size:
  code-font-size:
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Lato, Roboto, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif
  code-font-family: consolas, Menlo, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif

Blog字体

可自行设置字体的font-family
如不需要配置，请留空。
如不需要使用网络字体，只需要把font_link留空就行

修改 主题配置文件

1
2
3
4
5
# Font settings for the site title and site subtitle
# 左上角网站名字 主页居中网站名字
blog_title_font:
  font_link: https://fonts.googleapis.com/css?family=Titillium+Web&display=swap
  font-family: Titillium Web, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft JhengHei', 'Microsoft YaHei', sans-serif

网站副标题

可设置主页中显示的网站副标题或者喜欢的座右铭。

修改 主题配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 主页subtitle
subtitle:
  enable: false
  # Typewriter Effect (打字效果)
  effect: true
  # loop (循环打字)
  loop: true
  # source 调用第三方服务
  # source: false 关闭调用
  # source: 1  调用一言网的一句话（简体） https://hitokoto.cn/
  # source: 2  调用一句网（简体） http://yijuzhan.com/
  # source: 3  调用今日诗词（简体） https://www.jinrishici.com/
  # subtitle 会先显示 source , 再显示 sub 的内容
  source: false
  # 如果关闭打字效果，subtitle 只会显示 sub 的第一行文字
  sub:
    - 今日事&#44;今日毕
    - Never put off till tomorrow what you can do today

主页top_img显示大小

适用于 版本号 >= V1.2.0

默认的显示为全屏。site-info的区域会居中显示

1
2
3
4
5
# 主页设置
# 默认top_img全屏，site_info在中间
# 使用默认, 都无需填写（建议默认）
index_site_info_top: # 主页标题距离顶部距离  例如 300px/300em/300rem/10%
index_top_img_height:  #主页top_img高度 例如 300px/300em/300rem  不能使用百分比

注意：index_top_img_height的值不能使用百分比。
2个都不填的话，会使用默认值

举例，当

1
index_top_img_height: 400px

页面加载动画preloader

当进入网页时，因为加载速度的问题，可能会导致top_img图片出现断层显示，或者网页加载不全而出现等待时间，开启preloader后，会显示加载动画，等页面加载完，加载动画会消失。

修改主题配置文件

1
2
# 加载动画 Loading Animation
preloader: true

图片懒加载动画

安装插件

1
npm install hexo-lazyload-image --save

修改/添加 根目录配置文件

1
2
3
4
5
6
lazyload:
  enable: true
  onlypost: false # optional
  loadingImg: /assets/img/loading.gif # optional eg ./images/loading.gif
  isSPA: true # optional
  preloadRatio: 3 # optional, default is 1
配置 解释
onlypost true：只有路由页面或者文章的图片才会被懒加载。
false：除了站点背景图（如果有的话），整个站点的图片均会被懒加载。
isSPA true：针对单页面应用，当滚动条滚动到图片位置时就会向后端请求图片
flase：刷新才能请求图片
preloadRatio 在多少倍的可见区域时触发图片请求，默认为1，即当前屏幕的区域。

PWA

要为Butterfly配上 PWA 特性, 你需要如下几个步骤:

  1. 打开 hexo 工作目录

  2. npm install hexo-offline --save 或者 yarn add hexo-offline

  3. 在根目录创建 hexo-offline.config.cjs 文件，并增加以下内容。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    // offline config passed to workbox-build.
    module.exports = {
      globPatterns: ['**/*.{js,html,css,png,jpg,gif,svg,webp,eot,ttf,woff,woff2}'],
      // 静态文件合集，如果你的站点使用了例如 webp 格式的文件，请将文件类型添加进去。
      globDirectory: 'public',
      swDest: 'public/service-worker.js',
      maximumFileSizeToCacheInBytes: 10485760, // 缓存的最大文件大小，以字节为单位。
      skipWaiting: true,
      clientsClaim: true,
      runtimeCaching: [ // 如果你需要加载 CDN 资源，请配置该选项，如果没有，可以不配置。
        // CDNs - should be CacheFirst, since they should be used specific versions so should not change
        {
          urlPattern: /^https:\/\/cdn\.example\.com\/.*/, // 可替换成你的 URL
          handler: 'CacheFirst'
        }
      ]
    }

    更多内容请查看 hexo-offline的官方文档

  4. 在主题配置文件中开启 pwa 选项。

    1
    2
    3
    4
    5
    6
    7
    pwa:
      enable: true
      manifest: /img/pwa/manifest.json
      apple_touch_icon: /img/pwa/apple-touch-icon.png
      favicon_32_32: /img/pwa/32.png
      favicon_16_16: /img/pwa/16.png
      mask_icon: /img/pwa/safari-pinned-tab.svg

  5. 在创建source/目录中创建manifest.json文件。

    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
    {
        "name": "string",
        "short_name": "Junzhou",
        "theme_color": "#49b1f5",
        "background_color": "#49b1f5",
        "display": "standalone",
        "scope": "/",
        "start_url": "/",
        "icons": [
            {
              "src": "images/pwaicons/36.png",
              "sizes": "36x36",
              "type": "image/png"
            },
            {
                "src": "images/pwaicons/48.png",
              "sizes": "48x48",
              "type": "image/png"
            },
            {
              "src": "images/pwaicons/72.png",
              "sizes": "72x72",
              "type": "image/png"
            },
            {
              "src": "images/pwaicons/96.png",
              "sizes": "96x96",
              "type": "image/png"
            },
            {
              "src": "images/pwaicons/144.png",
              "sizes": "144x144",
              "type": "image/png"
            },
            {
              "src": "images/pwaicons/192.png",
              "sizes": "192x192",
              "type": "image/png"
            },
            {
                "src": "images/pwaicons/512.png",
                "sizes": "512x512",
                "type": "image/png"
              }
          ],
          "splash_pages": null
      }

    你也可以通过 Web App Manifest快速创建manifest.json。（Web App Manifest 要求至少包含一个 512*512 像素的图标）

  6. 可以通过Chrome插件Lighthouse检查 PWA 配置是否生效以及配置是否正确。

    • 打开博客页面
    • 启动Lighthouse插件 (Lighthouse插件要求至少包含一个 512*512 像素的图标)

关于 PWA（渐进式增强 Web 应用）的更多内容请参閲 Google Tools for Web Developers

字数统计

要为Butterfly配上字数统计特性, 你需要如下几个步骤:

  1. 打开 hexo 工作目录

  2. npm install hexo-wordcount --save or yarn add hexo-wordcount

  3. 修改 主题配置文件:

    1
    2
    3
    4
    5
    wordcount:
      enable: true
      post_wordcount: true
      min2read: true
      total_wordcount: true

图片大图查看模式

只能开启一个，如果你并不想为某张图片添加大图查看模式，你可以使用 html 格式引用图片，併为图片添加 no-lightbox class 名。

1）fancybox

修改 主题配置文件

1
2
# fancybox http://fancyapps.com/fancybox/3/
fancybox: true

2）medium_zoom

1
medium_zoom: true

Snackbar 弹窗

Snackbar 弹窗,根据自己爱好开启

修改 主题配置文件

1
2
3
4
5
6
7
8
9
# Snackbar 弹窗
# https://github.com/polonel/SnackBar
# position 弹窗位置
# 可选 top-left / top-center / top-right / bottom-left / bottom-center / bottom-right
snackbar:
  enable: true
  position: bottom-left
  bg_light: '#49b1f5' #light mode时弹窗背景
  bg_dark: '#2d3035' #dark mode时弹窗背景

其它配置

css前缀

有些 CSS 并不是所有浏览器都支持，需要增加对应的前缀才会生效。

开启 css_prefix 后，会自动为一些 CSS 增加前缀。（会增加 20%的体积）

修改配置文件

1
2
# Add the vendor prefixes to ensure compatibility
css_prefix: true

Open Graph

在 head 里增加一些 meta 资料，例如缩略图、标题、时间等等。当你分享网页到一些平台时，平台会读取 Open Graph 的内容，展示缩略图，标题等等信息。

修改配置文件

1
2
3
# Open graph meta tags
# https://developers.facebook.com/docs/sharing/webmasters/
Open_Graph_meta: true

Instantpage

当鼠标悬停到链接上超过 65 毫秒时，Instantpage 会对该链接进行预加载，可以提升访问速度。

修改配置文件

1
2
3
# https://instant.page/
# prefetch (预加载)
instantpage: true

Pangu

如果你跟我一样，每次看到网页上的中文字和英文、数字、符号挤在一块，就会坐立难安，忍不住想在它们之间加个空格。这个外挂正是你在网路世界走跳所需要的东西，它会自动替你在网页中所有的中文字和半形的英文、数字、符号之间插入空白。

修改配置文件

1
2
3
4
5
# https://github.com/vinta/pangu.js
# Insert a space between Chinese character and English character (中英文之间添加空格)
pangu:
  enable: false
  field: post # site/post

field只支持两个参数，post(只在文章页生效)和site(全站生效)

Pjax

当用户点击链接，通过ajax更新页面需要变化的部分，然后使用HTML5的pushState修改浏览器的URL地址。

这样可以不用重复加载相同的资源（css/js）， 从而提升网页的加载速度。

1
2
3
4
5
6
7
8
# Pjax [Beta]
# It may contain bugs and unstable, give feedback when you find the bugs.
# https://github.com/MoOx/pjax
pjax: 
  enable: true
  exclude:
    - /music/
    - /no-pjax/

对于一些第三方插件，有些并不支持 pjax 。
你可以把网页加入到 exclude 里，这个网页会被 pjax 排除在外。
点击该网页会重新加载网站

使用pjax后，一些自己DIY的js可能会无效，跳转页面时需要重新调用，请参考Pjax文档
使用pjax后，一些个别页面加载的js/css，将会改为所有页面都加载

Butterfly的Pjax目前仍有一些问题，请留意

  • 使用谷歌广告可能会报错（例如自动广告）

如果你在使用中发现问题，欢迎反馈Bugs

Inject

2.3.0以上支持

如想添加额外的js/css/meta等等东西，可以在Inject里添加，支持添加到head(</body>标籤之前)和bottom(</html>标籤之前)。

请注意：以标準的html格式添加内容

例如

1
2
3
4
5
inject:
  head:
  	- <link rel="stylesheet" href="/self.css">
  bottom:
  	- <script src="xxxx"></script>

留意: 如果你的网站根目录不是’/‘,使用本地图片时，需加上你的根目录。
例如：网站是 https://yoursite.com/blog,引用css/xx.css，则设置为<link rel="stylesheet" href="/blog/css/xx.css>"

CDN

配置文件中最后一部分CDN，里面是主题所引用到的文件，可自行配置CDN。（非必要请勿修改，配置后请确认链接是否能访问）

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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
CDN:
  # The CDN provider of internal scripts (主题内部 js 的 cdn 配置)
  # option: local/jsdelivr/unpkg/cdnjs/custom
  # Dev version can only choose. ( dev版的主题只能设置为 local )
  internal_provider: local

  # The CDN provider of third party scripts (第三方 js 的 cdn 配置)
  # option: local/jsdelivr/unpkg/cdnjs/custom
  # when set it to local, you need to install hexo-butterfly-extjs
  third_party_provider: jsdelivr

  # Add version number to CDN, true or false  
  version: false

  # Custom format
  # For example: https://cdn.staticfile.org/${cdnjs_name}/${version}/${min_cdnjs_file}
  custom_format:

  option:
    # main_css:
    # main:
    # utils:
    # translate:
    # local_search:
    # algolia_js:
    # algolia_search_v4:
    # instantsearch_v4:
    # pjax:
    # gitalk:
    # gitalk_css:
    # blueimp_md5:
    # valine:
    # disqusjs:
    # disqusjs_css:
    # twikoo:
    # waline_js:
    # waline_css:
    # sharejs:
    # sharejs_css:
    # mathjax:
    # katex:
    # katex_copytex:
    # mermaid:
    # canvas_ribbon:
    # canvas_fluttering_ribbon:
    # canvas_nest:
    # lazyload:
    # instantpage:
    # typed:
    # pangu:
    # fancybox_css_v4:
    # fancybox_v4:
    # medium_zoom:
    # snackbar_css:
    # snackbar:
    # activate_power_mode:
    # fireworks:
    # click_heart:
    # ClickShowText:
    # fontawesomeV6:
    # flickr_justified_gallery_js:
    # flickr_justified_gallery_css:
    # aplayer_css:
    # aplayer_js:
    # meting_js:
    # prismjs_js:
    # prismjs_lineNumber_js:
    # prismjs_autoloader:
参数 解释
internal_provider 主题内部文件
可选 local/jsdelivr/unpkg/cdnjs/custom
lcoal 为本地加载，custom 为自定义格式，需配置 custom_format
注意: 如果使用的是 Dev 版，只能设置为 local
third_party_provider 第三方文件
可选 local/jsdelivr/unpkg/cdnjs/custom
lcoal 为本地加载，custom 为自定义格式，需配置 custom_format
注意: 如果你选择 local 需要安装 hexo-butterfly-extjs插件
version true/false 为 cdn 加上指定版本号
custom_format 自定义格式
option 你可以在这里更换部分文件,会覆盖原有的配置

version

如需修改版本号，可修改主题目录的 ‘plugins.yml’ 中对应插件的 version

请确保你修改的版本号，你所使用的 cdn 有收录

custom_format

提供以下参数

参数 解释
name npm 上的包名
file npm 上的文件路径
min_file npm 上的文件路径（压缩过的文件）
cdnjs_name cdnjs 上的包名
cdnjs_file cdnjs 上的文件路径
min_cdnjs_file cdnjs 上的文件路径（压缩过的文件）
version 插件版本号

部分可用的第三方 CDN 列表

请确保你选择的 CDN 有收录主题使用的第三方插件

提供商 格式 备註
Staticfile(七牛云) https://cdn.staticfile.org/${cdnjs_name}/${version}/${min_cdnjs_file} 同步 cdnjs
BootCDN https://cdn.bootcdn.net/ajax/libs/${cdnjs_name}/${version}/${min_cdnjs_file} 同步 cdnjs
Baomitu(360) 最新版本： https://lib.baomitu.com/${cdnjs_name}/latest/${min_cdnjs_file}
指定版本：https://lib.baomitu.com/${cdnjs_name}/${version}/${min_cdnjs_file}		 同步 cdnjs
Elemecdn 最新版本： https://npm.elemecdn.com/${name}@latest/${file}
指定版本：https://npm.elemecdn.com/${name}@${version}/${file}		 同步 npm

音乐

音乐界面使用了插件 hexo-tag-aplayer
使用方法请参考插件文档

音乐页面只是普通的page页，按普通页面操作生成就行。

以下内容可供选择配置

注意： 仍需要安装插件hexo-tag-aplayer

插件会在每一个文件都插入 js 和 css，为了避免这一情况，3.0 版本内置了 aplayer 需要的 css 和 js。

首先在Hexo根目录_config里配置asset_inject为false

1
2
aplayer:
  asset_inject: false

然后在你需要使用aplayer的页面Front-matter添加

1
aplayer: true

这样只会在需要aplayer的页面插入js和css。

Butterfly添加全局吸底Aplayer教程

1）前言

如果你想使用 aplayer，很多人都会推荐安装 hexo-tag-aplayer 这款插件。这款插件通过 Hexo 独有的标籤外挂，我们可以很方便的写入一些参数，插件就会帮我们生成对应的 html。如果你只是使用一些简单的功能，其实无需使用到这个插件，只需以 html 格式书写就行，不用插件去转换。

例如：

如果使用插件，在 markdown 中要这样写

1
{% meting "000PeZCQ1i4XVs" "tencent" "artist" "theme:#3F51B5" "mutex:true" "preload:auto" %}

其会被插件渲染为

1
<div id="aplayer-uxAIfEUs" class="aplayer aplayer-tag-marker meting-tag-marker" data-id="000PeZCQ1i4XVs" data-server="tencent" data-type="artist" data-mode="circulation" data-autoplay="false" data-mutex="true" data-listmaxheight="340px" data-preload="auto" data-theme="#3F51B5"></div>

如果我们不想使用插件，就需要在markdown中用html的格式书写，同时把主题配置文件中的aplayerInject开启

1
<div class="aplayer" data-id="000PeZCQ1i4XVs" data-server="tencent" data-type="artist" data-mutex="true" data-preload="auto" data-theme="#3F51B5"></div>

2）回到正题，如何在Butterfly上使用全局吸底 Aplayer

需先安装aplayer

1
npm install aplayer --save

  1. 关闭 asset_inject

    由于需要全局都插入 aplayer 和 meting 资源，为了防止插入重复的资源，需要把 asset_inject 设为 false

    在 Hexo 的配置文件中

    1
    2
    3
    aplayer:
      meting: true
      asset_inject: false

  2. 开启主题的 aplayerInject

    在主题的配置文件中，enable 设为 true 和 per_page 设为 true

    1
    2
    3
    4
    # Inject the css and script (aplayer/meting)
    aplayerInject:
      enable: true
      per_page: true

  3. 插入 Aplayer html

    为了适配 hexo-tag-aplayer，主题内置的 Meting js 仍为 1.2 版本，并非最新的 2.x 版本。

    Aplayer html 例子：

    1
    <div class="aplayer no-destroy" data-id="60198" data-server="netease" data-type="playlist" data-fixed="true" data-autoplay="true"> </div>

参数解释

option default description
data-id require song id / playlist id / album id / search keyword
data-server require music platform: netease, tencent, kugou, xiami, baidu
data-type require song, playlist, album, search, artist
data-fixed false enable fixed mode
data-mini false enable mini mode
data-autoplay false audio autoplay
data-theme #2980b9 main color
data-loop all player loop play, values: ‘all’, ‘one’, ‘none’
data-order list player play order, values: ‘list’, ‘random’
data-preload auto values: ‘none’, ‘metadata’, ‘auto’
data-volume 0.7 default volume, notice that player will remember user setting, default volume will not work after user set volume themselves
data-mutex true prevent to play multiple player at the same time, pause other players when this player start play
data-lrctype 0 lyric type
data-listfolded false indicate whether list should folded at first
data-listmaxheight 340px list max height
data-storagename metingjs localStorage key that store player setting

require 代表着这些参数是必须要使用的，其它的参数则可以根据自己需要配置。

配置全局吸底，data-fixed 和 data-mini 也必须配置，配置为 true

如果使用 Pjax，则在 class 里需添加 no-destroy，这样防止切换页面时 Aplayer 被销毁

把 aplayer代码 插入到主题配置文件的 inject.bottom 去

1
2
3
4
inject:
  head:
  bottom:
    - <div class="aplayer no-destroy" data-id="60198" data-server="netease" data-type="playlist" data-fixed="true" data-autoplay="true"> </div>

运行 Hexo 就可以看到网页左下角出现了 Aplayer

最后，如果你想切换页面时，音乐不会中断。请把主题配置文件的 pjax 设为 true

电影/说说等等

暂时不需要

链接

一些错误解决及建议

不要把个人需要的文件/图片放在主题source文件夹里，因为在升级主题的过程中，可能会把文件覆盖删除了。
在Hexo根目录的source文件夹里，创建一个文件夹来放置个人文件/图片。
引用文件直接为/文件夹名称/文件名

链接