Hexo安装并使用Butterfly主题

前置说明

本片文章为本人想要换hexo的主题时所写。因此省略

node

和

hexo

的安装，直接在初始化博客开始

初始化博客

输入一下命令，并等待程序初始化完成。

hexo init MyHexoBlog

复制

此时已初始化完成。

安装主题

如果没有cheerio安装 npm install [email protected] --save

在你的博客根目录里

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

我这里选择dev分支。

等待克隆完成。

启用主题

修改站点配置文件_config.yml，把主题改为Butterfly

theme: Butterfly

复制

如果你没有 pug 以及 stylus 的渲染器，请下载安装： npm install hexo-renderer-pug hexo-renderer-stylus --save or yarn add hexo-renderer-pug hexo-renderer-stylus

平滑升级

为了主题的平滑升级,

Butterfly

使用了 data files特性。

推荐把主题默认的配置文件

_config.yml

复製到 Hexo 工作目录下的

source/_data/butterfly.yml

，如果

source/_data

的目录不存在那就创建一个。

注意，如果你创建了 butterfly.yml , 它将会替换主题默认配置文件 _config.yml 里的配置项 (不是合併而是替换), 之后你就只需要通过git pull的方式就可以平滑地升级 theme-butterfly 了。

主题页面

Page Front-matter

---
title:
date:
type: （tags,link,categories这三个页面需要配置）
comments: (是否需要显示评论，默认true)
description:
top_img: (设置顶部图)
mathjax:
katex:
---

复制

Post Front-matter

---
title:
date:
tags:
categories:
keywords:
description:
top_img: （除非特定需要，可以不写）
comments  是否显示评论（除非设置false,可以不写）
cover:  缩略图
toc:  是否显示toc （除非特定文章设置，可以不写）
toc_number: 是否显示toc数字 （除非特定文章设置，可以不写）
copyright: 是否显示版权 （除非特定文章设置，可以不写）
mathjax:
katex:
hide:
---

复制

标签页

前往你的 Hexo 博客的根目录
输入 hexo new page tags
你会找到 source/tags/index.md 这个文件
修改这个文件：

--- title: 标签 date: 2020-02-02 10:00:00 type: "tags" ---

分类页

前往你的 Hexo 博客的根目录
输入 hexo new page categories
你会找到source/categories/index.md这个文件
修改这个文件：

--- title: 分类 date: 2020-02-02 10:00:00 type: "categories" ---

友情链接

前往你的 Hexo 博客的根目录
输入 hexo new page link
你会找到``source/link/index.md`这个文件
修改这个文件：

---
title: 友情链接
date: 2020-02-02 10:00:00
type: "link"
---

复制

添加友链

在Hexo博客目录中的
source/_data ，创建一个文件 link.yml

class:
  class_name: 友情链接
  link_list:
    1:
      name: 小康博客
      link: https://www.antmoe.com
      avatar: https://img.antmoe.com/avatar.png
      descr: 每天进步一点点
    2:
      name: test
      link: https://www.xxxxxxcn/
      avatar: https://xxxxx/avatar.png
      descr: test  


class2:
   class_name: 链接无效
   link_list:
     1:
       name: test
       link: https://blog.xxx.com
       avatar: https://img.antmoe.com/avatar.png
       descr: test
     2:
       name: test
       link: https://www.axxxx.cn/
       avatar: https://img.antmoe.com/avatar.png
       descr: test

复制

友情链接界面设置

需要添加友情链接，可以在
Butterfly.yml
配置

可在友情链接上写上自己的个人资料，方便其他人添加。

Flink:
  headline: 友情链接
  info_headline: 我的Blog资料
  name: Blog 名字： 小康博客
  address: Blog 地址： https://www.antmoe.com/
  avatar: Blog 头像： https://img.antmoe.com/avatar.jpg
  info: Blog 简介： 一个收藏回忆与分享技术的地方！
  comment: 如果需要交换友链,请留言

复制

音乐界面

音乐界面参考https://github.com/MoePlayer/hexo-tag-aplayer/blob/master/docs/README-zh_cn.md

电影

电影界面参考https://github.com/mythsman/hexo-douban

本人没有设置这两个界面，因此也没有详细的安装教程

配置

语言

修改站点配置文件

_config.yml

默认语言是

en

主题支持三种语言

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

网站资料

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

_config.yml

title: 小康博客
subtitle: '小康博客'
description: '一个收藏回忆与分享技术的地方！'
keywords: 关键词
author: 作者
language: zh-CN
timezone: '时区'
email: 邮箱

复制

导航菜单

menu:
  Home: / || fa fa-home
  Archives: /archives/ || fa fa-archive
  Tags: /tags/ || fa fa-tags
  Categories: /categories/ || fa fa-folder-open
  Link: /link/ || fa fa-link
  About: /about/ || fa fa-heart
  #List||fa fa-list:
   # - Music || /music/ || fa fa-music
   # - Movie || /movies/ || fa fa-film

复制

必须是 /xxx/，后面||分开，然后写图标名。菜单名称可自己修改

格式：

显示名称:

路径||icon

sub-menu格式

名称||icon:

名称 || 路径 || icon

导航的文字可以更改

menu:
  首页: / || fa fa-home
  时间轴: /archives/ || fa fa-archive
  标籤: /tags/ || fa fa-tags
  分类: /categories/ || fa fa-folder-open
  清单||fa fa-heartbeat:
    - 音乐 || /music/ || fa fa-music
    - 照片 || /Gallery/ || fa fa-picture-o
    - 电影 || /movies/ || fa fa-film
  友链: /link/ || fa fa-link
  关于: /about/ || fa fa-heart

复制

代码

Butterfly 支持了 Material Theme全部 5 种代码高亮样式：

default
darker
pale night
light
ocean

配置

butterfly.yml

highlight_theme: light #代码高亮主题
highlight_copy: true #代码是否启用复制功能
highlight_shrink: true #true代码框不展开，需点击 '>' 打开 false展开 none不显示'>'按钮，代码块展开

复制

自动换行

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

配置butterfly.yml

code_word_wrap: true #代码自动换行

复制

然后找到你站点的 Hexo 配置文件

_config.yml

，将

line_number

改成

false

highlight:
  enable: true
  line_number: false
  auto_detect: false
  tab_replace:

复制

社交图标

Butterfly支持 font-awesome v4和 font-awesome v5. 如需开启font-awesome v5,需要在

Butterfly.yml

上开启

CDN_USE:
  css:
    - https://cdn.jsdelivr.net/npm/font-awesome@latest/css/font-awesome.min.css
    - https://use.fontawesome.com/releases/v5.8.1/css/all.css

复制

无论V4还是V5,书写格式都是一样的

图标名：url

social:
  fa fa-qq: tencent://AddContact/?fromId=50&fromSubId=1&subcmd=all&uin=535668586
  fa fa-envelope: mailto:[email protected]
  fa fa-rss: /atom.xml

复制

主页文章节选(自动节选和文章页description)

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

在

butterfly.yml

里可以开启

auto_excerpt

的选项，你的文章将会在自动截取部分显示在主页。（默认显示150个字）。

auto_excerpt:
  enable: true
  length: 150

复制

如果没有开启

自动节选

，则会显示文章页front-matter里面设置的

description

。

注意：如果开启了自动节选功能，代码块的显示将有可能不正常。

顶部图

顶部图有2种配置：具体url 和（留空，true和false，三个效果一样）

page页

当具体url时

主页的顶部图可以在

Butterfly.yml

设置

index_img

archives页的顶部图可以在

Butterfly.yml

设置

archive_img

其他

page

页的顶部图可以在各自的md页面设置

front-matter

中的

top_img

页面如果没有设置各自的top_img，则会显示default_top_img图片

当顶部图留空，

true

和

false

主页会显示纯颜色的顶部图

其他page的顶部图没有设置时，也会显示纯颜色的顶部图

post页

post

页的顶部图会优先显示各自

front-matter

中的

top_img

,如果没有设置，则会缩略图（即各自

front-matter

中的

cover

)，如果没有则会显示显示

default_top_img

图片

文章相关项

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

butterfly.yml

post_meta:
  date_type: both #可设置文章日期显示创建日期(created)或者更新日期(updated)或者两种都显示(both)
  categories: true # or false 是否显示分类
  tags: true # or false 是否显示标签

复制

文章版权

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

butterfly.yml

post_copyright:
  enable: true
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

复制

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

copyright: false

复制

文章打赏

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

butterfly.yml

reward:
  enable: true
  QR_code:
    - itemlist:
        img: /img/wechat.jpg
        text: 微信
    - itemlist:
        img: /img/alipay.jpg
        text: 支付宝

复制

文章的markdown文档上,在Front-matter添加

cover

,并填上要显示的图片地址。

如果不配置

cover

,可以设置显示默认的

cover

配置

butterfly.yml

default_cover: https://tva1.sinaimg.cn/large/832afe33ly1gbhxplql40j22801e0q3c.jpg

复制

当配置多张图片时,会随机选择一张作爲

cover

.此时写法应为

default_cover:
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg.png
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg2.png
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg3.png

复制

文章隐藏

参考https://github.com/printempw/hexo-hide-posts/blob/master/README_ZH.md

在文章的Front-matter添加

hide: true

复制

头像

配置

butterfly.yml

avatar: https://img.antmoe.com/avatar.jpg

复制

Footer设置

博客年份

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

配置

butterfly.yml

since: 2020

复制

页脚自定义文字

footer_custom_text

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

配置

butterfly.yml

footer_custom_text: Hi, welcome to my <a href="https://www.antmoe.com/">blog</a>!

复制

ICP

对于部分有备案的域名，可以在ICP配置显示。

配置

butterfly.yml

ICP:
  enable: true
  url: http://www.beian.miit.gov.cn/
  text: 粤ICP备xxxx
  icon: /img/icp.png

复制

右下角按钮

简繁转换

简体繁体互换

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

配置

butterfly.yml

translate:
  enable: true
  # 默认按钮显示文字(网站是简体，应设置为'default: 繁')
  default: 简
  #网站默认语言，1: 繁体中文, 2: 简体中文
  defaultEncoding: 1
  #延迟时间,若不在前, 要设定延迟翻译时间, 如100表示100ms,默认为0
  translateDelay: 0
  #博客网址
  cookieDomain: "https://jerryc.me/"
  #当文字是简体时，按钮显示的文字
  msgToTraditionalChinese: "繁"
  #当文字是繁体时，按钮显示的文字
  msgToSimplifiedChinese: "简"

复制

夜间模式

右下角会有夜间模式按钮

配置

butterfly.yml

# 夜间模式
darkmode:
  enable: true

复制

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

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

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

autoChangeMode: false 取消自动切换

# 自动切换 dark mode和 light mode
autoChangeMode: false

复制

阅读模式

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

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

配置

butterfly.yml

readmode:
  enable: true

复制

侧边设置

可自行决定哪个项目需要显示，可决定位置。（至少需要显示一个）

配置

butterfly.yml

aside:
  position: right # left or right
  card_author: true #作者卡片
  card_announcement: true #公告卡片
  card_recent_post: false #最新文章卡片
  card_categories: false #分类卡片
  card_tags: true #标签卡片
  card_archives: false #归档卡片
  card_webinfo: true #网站信息卡片

复制

访问人数

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

配置

butterfly.yml

busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

复制

运行时间

网页已运行时间

配置

butterfly.yml

runtimeshow:
  enable: true
  start_date: 2020/2/2 10:00:00  
  ##网页开通时间
  #格式: 月/日/年 时间
  #也可以写成 年/月/日 时间

复制

标签外挂

Note

移植于next主题（注意，书写不是markdown规范，而是hexo特有的功能，故在其它地方会显示不出效果）

配置

butterfly.yml

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: true
  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

复制

效果看这里

Gallery相册

{% gallery %}
markdown 图片格式
{% endgallery %}

复制

例如：

{% gallery %}
![](https://gratisography.com/wp-content/uploads/2019/10/gratisography-scary-pumpkin-hand-900x600.jpg)
![](https://gratisography.com/wp-content/uploads/2019/10/gratisography-fresh-fish-dinner-900x600.jpg)
![](https://gratisography.com/wp-content/uploads/2019/10/gratisography-mountain-cloud-landscape-900x600.jpg)
![](https://picjumbo.com/wp-content/uploads/iphone-free-stock-photos-2210x3315.jpg)
![](https://picjumbo.com/wp-content/uploads/young-millennial-girl-drinking-lemonade-and-overlooking-the-city-2210x1473.jpg)
![](https://picjumbo.com/wp-content/uploads/modern-graphic-designer-essentials_free_stock_photos_picjumbo_HNCK4919-2210x1474.jpg)
{% endgallery %}

复制

评论我只觉得Valine好用。配置遵循Valine

我选择默认的Sharejs就好

搜索系统

Algolia

你需要安装 hexo-algolia或 hexo-algoliasearch. 根据它们的説明文档去做相应的配置。
配置 butterfly.yml algolia_search: enable: true hits: per_page: 6 labels: input_placeholder: Search for Posts hits_empty: "We didn't find any results for the search: ${query}" # if there are no result hits_stats: "${hits} results found in ${time} ms"

本地搜索系统

你需要安装 hexo-generator-search. 根据它的文档去做相应配置。注意格式只支持 xml。
配置 butterfly.yml local_search: enable: false labels: input_placeholder: Search for Posts hits_empty: "We didn't find any results for the search: ${query}" # if there are no result

网页验证

如果需要搜索引擎收录网站，可能需要登录对应搜索引擎的管理平台进行提交。

各自的验证码可从各自管理平台拿到

配置

butterfly.yml

# Google Webmaster tools verification setting
# See: https://www.google.com/webmasters/
google_site_verification:

# Bing Webmaster tools verification setting
# See: https://www.bing.com/webmaster/
bing_site_verification:

# Yandex Webmaster tools verification setting
# See: https://webmaster.yandex.ru/
yandex_site_verification:

# Baidu Webmaster tools verification setting
# See: https://ziyuan.baidu.com/site/
baidu_site_verification:

# 360 Webmaster tools verification setting
# see http://zhanzhang.so.com/
qihu_site_verification:

复制

分析统计

统计找到各个平台找到代码即可

baidu_analytics: #百度统计
google_analytics: # 谷歌分析通常以`UA-`打头
tencent_analytics: #腾讯分析

复制

公式

MathJax

配置

butterfly.yml

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

复制

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

查看https://www.npmjs.com/package/hexo-renderer-kramed

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

复制

kramed:
  gfm: true
  pedantic: false
  sanitize: false
  tables: true
  breaks: true
  smartLists: true
  smartypants: true

复制

KaTeX(推荐)

首先禁用

MathJax

（如果你配置过 MathJax 的话），然后修改你的

butterfly.yml

以便加载

katex.min.css

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

复制

你不需要添加

katex.min.js

来渲染数学方程。相应的你需要卸载你之前的 hexo 的

markdown

渲染器以及

hexo-math

，然后安装新的

hexo-renderer-markdown-it-plus

# 替换 `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-math`
npm un hexo-math --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:

markdown_it_plus:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      enable: true
      options:
        strict: false

复制

美化/特效

自定义颜色

配置

butterfly.yml

，比如：

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

theme_color:
  enable: true
  main: "#9370DB"
  paginator: "#7A7FF1"
  button_hover: "#FF7242"
  text_selection: "#69c46d"
  link_color: "#858585"
  hr_color: "#A4D8FA"
  read-mode-bg_color: '#FAF9DE'

复制

网站背景

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

配置

butterfly.yml

# 图片格式 background: url(http://xxxxxx.com/xxx.jpg)
# 顔色 background: '#49B202'
# 留空 显示白色
background: "#efefef"
# background: url(https://i.loli.net/2019/09/09/5oDRkWVKctx2b6A.png)

复制

footer背景

footer 的背景会与

top_img

的一致, 当设置false时，将与主题色一致。

配置

butterfly.yml

# footer是否显示图片背景(与top_img一致)
footer_bg: true

复制

打字效果

配置

butterfly.yml

# 打字效果
activate_power_mode:
  enable: true
  colorful: true # 冒光特效
  shake: false # 抖动特效

复制

彩带

参考配置文件

鼠标点击效果

配置

butterfly.yml

文件

烟花

fireworks:
  enable: true

复制

爱心

click_heart:
  enable: true

复制

文字

ClickShowText:
  enable: false
  text: 
    - 富强
    - 民主
    - 文明
    - 和谐
    - 自由
    - 平等
    - 公正
    - 法治
    - 爱国
    - 敬业
    - 诚信
    - 友善
  fontSize: 15px

复制

文章页美化

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

配置

butterfly.yml

post_beautify:
  enable: true
  title-prefix-icon: '\f0c1'
  title-prefix-icon-color: "#F47466"

复制

title-prefix-icon

填写的是fontawesome的icon的Unicode数

自定义字体

可自行设置字体的

font-family

配置

butterfly.yml

font:
  enable: true
  font-family: Lato, Helvetica Neue For Number, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, PingFang SC, Hiragino Sans GB,"Microsoft JhengHei", "MicrMicrosoft YaHei", Helvetica Neue, Helvetica, Arial, sans-serif
  code-font: consolas, Menlo, "PingFang SC", "Microsoft JhengHei","Microsoft YaHei", monospace, Helvetica Neue For Number

复制

网站副标题

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

配置

butterfly.yml

# 主页subtitle
# 打字效果
subtitle: 
  enable: true
  # source调用第三方服务
  # source: false 关闭调用 
  # source: 1  调用金山词霸的每日一句（简体）
  # source: 2  调用一言网的一句话（简体） #https://hitokoto.cn/
  # source: 3  调用一句网（简体） http://yijuzhan.com/
  # source: 4  调用今日诗词（简体） https://www.jinrishici.com/
  # subtitle 会先显示 source , 再显示 sub 的内容
  source: false
  # (如果有英文逗号' , '，请使用转义字符 &#44;)
  sub:
    - 今日事&#44;今日毕
    - Never put off till tomorrow what you can do today

复制

主页文章cover位置

# 主页文章COVER显示位置
# 三个值可配置 left , right , both
# left(全部图片显示在左边)，right(全部图片显示在右边)，both(左右左右顺序显示)
index_post_cover: left

复制

主页top_img显示大小，默认的显示为全屏。site-info的区域会居中显示

# 主页设置
# 默认top_img全屏，site_info在中间
# 使用默认, 都无需填写（建议默认）
index_top_img_height:  #主页top_img高度 例如 300px/300em/300rem  不能使用百分比

复制

注意：index_top_img_height的值不能使用百分比。

2个都不填的话，会使用默认值

字数统计

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

打开 hexo 工作目录
npm install hexo-wordcount --save or yarn add hexo-wordcount
配置 butterfly.yml
:

wordcount: enable: true

文章置顶

要为你一些文章置顶，你需要如下步骤:

打开 hexo 工作目录
npm uninstall hexo-generator-index --save 然后 npm install hexo-generator-index-pin-top --save
你要在文章的 front-matter 区域里添加 top: True 属性来把这篇文章置顶。
你可以参考 hexo-generator-index-pin-top这个仓库来了解更多细节。

图片放大查看模式

fancybox

配置

butterfly.yml

# fancybox http://fancyapps.com/fancybox/3/
fancybox:
  enable: true

复制

medium_zoom

配置

butterfly.yml

medium_zoom:
  enable: true

复制

Snackbar 弹窗

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

配置

butterfly.yml

# 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时弹窗背景

复制