更新于 

butterfly基本配置

安装Butterfly

Git安装（Gitee）

稳定版(Github)


在你的 Hexo 根目录里 
1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

测试版可能存在 bug，追求稳定的请安装稳定版

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

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

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

Git安装（Gitee）

稳定版【建议】


在你的 Hexo 根目录里 
1
git clone -b master https://gitee.com/immyw/hexo-theme-butterfly.git themes/butterfly

测试版可能存在 bug，追求稳定的请安装稳定版

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

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

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

安装必要插件

如果你沒有 pug 以及 stylus 的渲染器，請下載安裝：

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

应用主题

打开hexo根目录下的config.js,把主题改为butterfly:

1
theme: butterfly

开始写作

创建新文章

在Hexo根目录下的soruce/_posts创建一个Markdown文件。

FrontMatter

https://butterfly.js.org/posts/dc584b87/#Front-matterFrontMatter在官网中有很明确的解释。

Markdown

Markdown的功能被我们称为”排版”，您可以在Markdown官网查看编写方式（很简单的啦~别这么严肃。）

Hexo基本配置

Hexo _config.yml修改

Hexo根目录下的_config.yml小白可以将其理解为Wordpress的wp-admin（比喻也许不恰当）主题根目录的_config.yml 可以是为主题设置。
在Hexo根目录下的config.js，您可以修改昵称，站点名称，站点语言，邮箱，关键词等个人资料，或是增加教程说明必要修改config.js的插件。

标题与子标题

在Hexo根目录下的_config.yml内找到title:与subtitle:按照自己的喜好填写。
Title会让站点的右上角显示您填写的文本，而配置完Subtitle，您只有在浏览器标题处才能感受到它带来的改变，此时标题处显示的是：title - subtitle。

关键词

在Hexo根目录下的_config.yml内找到keywords:按喜好填写。每词用英文逗号分隔。

语言

在Hexo根目录下的_config.yml内找到language:主题支持三种语言，为：

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

一般我们更改为zh-CN即可。

Butterfly基本配置

Butterfly _config.yml修改

重要建议

为了减少升级主题后带来的不便，请使用以下方法（本教程已全面使用，可以不做）。

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

以后只需要在 _config.butterfly.yml进行配置就行。
Hexo会自动合并主题中的_config.yml和 _config.butterfly.yml里的配置，如果存在同名配置，会使用_config.butterfly.yml的配置，其优先度较高。
:::

导航栏

修改_config.butterfly.yml:

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

内文字与网址可自由更改，如何创建页面，请看下一章中的：创建页面

代码高亮主题

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

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

修改_config.butterfly.yml

1
highlight_theme: light

darker
darker主题

pale night
pale night主题

light
light主题

ocean
ocean主题

mac
mac主题

mac light
mac light主题

代码复制

这是一个网站内常用的功能，建议开启，否则访问者触控板的复制体验很差（至少我是这样的😂），开启这个功能后，代码框右上角会显示copy图标。
修改_config.butterfly.yml

1
highlight_copy: true

代码自动换行

默认情况下，Hexo 在编译的时候不会实现代码自动换行。如果您想使站点更美观，可以尝试。但是我们不建议您这么做，这样会让无法正常使用行号。
修改_config.butterfly.yml

1
code_word_wrap: true

使用highlight 渲染的用户需要在站点根目录下的_config.yml中将line_number改为false:

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

使用prismjs 渲染的用户需要在站点根目录下的_config.yml中将line_number改为false:

1
2
3
4
5
prismjs:
  enable: false
  preprocess: true
  line_number: false
  tab_replace: ''

代码高度限制

::: tip 支持版本
3.7.0 及以上支持
:::
可配置代码高度限制，超出的部分会隐藏，并显示展开按钮。

1
highlight_height_limit: false # unit: px

::: warning 注意

单位是 px，直接添加数字，如 200

实际限制高度为 highlight_height_limit + 30 px ，多增加 30px 限制，目的是避免代码高度只超出highlight_height_limit 一点时，出现展开按钮，展开没内容。

不适用于隐藏后的代码块（ 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

您可以在侧边栏的作者信息内找到它带来的改动。

顶部图

::: tip
如果不要显示顶部图，可直接配置 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。

文章meta显示

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

修改 _config.butterfly.yml:

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 显示描述性文字

当然，我们建议您使用both，若您想将博客的recent-posts修改为HEO旧样式，那么我们建议您修改为left。

文章封面

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

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

修改 _config.butterfly.yml

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

文章版权

修改 _config.butterfly.yml

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可以不写，会默认为图片的链接。

修改 _config.butterfly.yml

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: 支付宝

相关文章

相关文章推荐的原理是根据文章tags的比重来推荐
修改 _config.butterfly.yml

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

文章过期提醒

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 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：天数之后的文字

文章编辑按钮

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

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 下一篇显示的是新文章

头像

修改 _config.butterfly.yml

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

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

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

修改_config.butterfly.yml

1
photofigcaption: true

复制相关配置

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

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

当然，我们强烈建议您打开此功能，虽然复制时的Copyright在复制代码时（所以我们在上几章强烈建议您开启copy按钮），此功能的开启给我们的代码复制增加了负担。

简繁转换(右下角按钮)

右下角会有简繁转换按钮。

修改 _config.butterfly.yml

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: "简"

夜间模式(右下角按钮)

右下角会有夜间模式按钮

修改 _config.butterfly.yml

1
2
3
4
5
6
# dark mode
darkmode:
  enable: true
  # dark mode和 light mode切换按钮
  button: true
  autoChangeMode: false

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

修改_config.butterfly.yml

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

访问人数 busuanzi (UV 和 PV)

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

修改_config.butterfly.yml

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

运行时间

修改_config.butterfly.yml

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

完。