文章作者: DreamyTZK
文章連結: https://www.antmoe.com/posts/75a6347a/
版權聲明: 著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。
前置说明
本片文章为本人想要换 hexo 的主题时所写。因此省略 node 和 hexo 的安装，直接在初始化博客开始。
初始化博客
输入一下命令，并等待程序初始化完成。
BASH
hexo init MyHexoBlog
此时已初始化完成。
安装主题
如果没有 cheerio 安装
npm install cheerio@0.22.0 --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
YAML
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
MARKDOWN---
title:
date:
type: （tags,link,categories这三个页面需要配置）
comments: (是否需要显示评论，默认true)
description:
top_img: (设置顶部图)
mathjax:
katex:
---
Post Front-matter
MARKDOWN---
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这个文件 -
修改这个文件：
MARKDOWN--- title: 标签 date: 2020-02-02 10:00:00 type: "tags" ---
分类页
-
前往你的 Hexo 博客的根目录
-
输入
hexo new page categories -
你会找到 source/categories/index.md 这个文件
-
修改这个文件：
MARKDOWN--- title: 分类 date: 2020-02-02 10:00:00 type: "categories" ---
友情链接
-
前往你的 Hexo 博客的根目录
-
输入
hexo new page link -
你会找到 ``source/link/index.md` 这个文件
-
修改这个文件：
MARKDOWN--- title: 友情链接 date: 2020-02-02 10:00:00 type: "link" --- -
添加友链
在 Hexo 博客目录中的
source/_data，创建一个文件link.ymlYAMLclass: 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配置
可在友情链接上写上自己的个人资料，方便其他人添加。YAMLFlink: 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
YAMLtitle: 小康博客
subtitle: '小康博客'
description: '一个收藏回忆与分享技术的地方！'
keywords: 关键词
author: 作者
language: zh-CN
timezone: '时区'
email: 邮箱
导航菜单
YAMLmenu:
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
导航的文字可以更改
YAMLmenu:
首页: / || 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
YAMLhighlight_theme: light #代码高亮主题
highlight_copy: true #代码是否启用复制功能
highlight_shrink: true #true代码框不展开，需点击 '>' 打开 false展开 none不显示'>'按钮，代码块展开
自动换行
在默认情况下，hexo-highlight 在编译的时候不会实现代码自动换行。如果你不希望在代码块的区域里有横向滚动条的话，那么你可以考虑开启这个功能。
配置 butterfly.yml
YAML
code_word_wrap: true #代码自动换行
然后找到你站点的 Hexo 配置文件_config.yml，将 line_number 改成 false:
YAMLhighlight:
enable: true
line_number: false
auto_detect: false
tab_replace:
社交图标
Butterfly 支持 font-awesome v4 和 font-awesome v5. 如需开启 font-awesome v5, 需要在 Butterfly.yml 上开启
YAMLCDN_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
YAMLsocial:
fa fa-qq: tencent://AddContact/?fromId=50&fromSubId=1&subcmd=all&uin=535668586
fa fa-envelope: mailto:sviptzk@163.com
fa fa-rss: /atom.xml
主页文章节选 (自动节选和文章页 description)
因为主题 UI 的关系，主页文章节选只支持自动节选和文章页 description。优先选择自动节选。
在 butterfly.yml 里可以开启 auto_excerpt 的选项，你的文章将会在自动截取部分显示在主页。（默认显示 150 个字）。
YAMLauto_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
YAMLpost_meta:
date_type: both #可设置文章日期显示创建日期(created)或者更新日期(updated)或者两种都显示(both)
categories: true # or false 是否显示分类
tags: true # or false 是否显示标签
文章版权
为你的博客文章展示文章版权和许可协议。配置 butterfly.yml
YAMLpost_copyright:
enable: true
license: CC BY-NC-SA 4.0
license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
如果有文章（例如：转载文章）不需要显示版权，可以在文章 Front-matter 单独设置
YAML
copyright: false
文章打赏
在你每篇文章的结尾，可以添加打赏按钮。相关二维码可以自行配置 配置 butterfly.yml
YAMLreward:
enable: true
QR_code:
- itemlist:
img: /img/wechat.jpg
text: 微信
- itemlist:
img: /img/alipay.jpg
text: 支付宝
文章的 markdown 文档上，在 Front-matter 添加 cover, 并填上要显示的图片地址。
如果不配置 cover, 可以设置显示默认的 cover.
配置 butterfly.yml
YAML
default_cover: https://tva1.sinaimg.cn/large/832afe33ly1gbhxplql40j22801e0q3c.jpg
当配置多张图片时，会随机选择一张作爲 cover. 此时写法应为
YAMLdefault_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 添加
MARKDOWN
hide: true
头像
配置 butterfly.yml
YAML
avatar: https://img.antmoe.com/avatar.jpg
TOC
在文章页，会有一个目录，用于显示 TOC。 手机端默认显示按钮。
配置 butterfly.yml
YAMLtoc:
enable: true
number: true #显示章节数字
为特定的文章配置是否显示 TOC 和特定的目录章节数字
在你的文章 md 文件的头部，加入 toc_number 和 toc 项，并配置 true 或者 false 即可。
toc 是否显示文章 TOC
toc_number 是否显示章节数
配置之后你的特定的文章将会拥有它自己的目录数字的显示与否，而不会受全局的配置影响。
自动打开 TOC
可选择进入文章页面时，是否自动打开 sidebar 显示 TOC
YAMLauto_open_sidebar:
enable: true
相关文章
相关文章推荐的原理是根据文章 tags 的比重来推荐
配置 butterfly.yml
YAMLrelated_post:
enable: true
limit: 6 # 显示推荐文章数目
date_type: created # or created or updated 文章日期显示创建日或者更新日
Footer 设置
博客年份
since 是一个来展示你站点起始时间的选项。它位于页面的最底部。
配置 butterfly.yml
YAML
since: 2020
页脚自定义文字
footer_custom_text 是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等。支持 HTML。
配置 butterfly.yml
YAML
footer_custom_text: Hi, welcome to my <a href="https://www.antmoe.com/">blog</a>!
ICP
对于部分有备案的域名，可以在 ICP 配置显示。
配置 butterfly.yml
YAMLICP:
enable: true
url: http://www.beian.miit.gov.cn/
text: 粤ICP备xxxx
icon: /img/icp.png
右下角按钮
简繁转换
简体繁体互换
右下角会有简繁转换按钮。
配置 butterfly.yml
YAMLtranslate:
enable: true
# 默认按钮显示文字(网站是简体，应设置为'default: 繁')
default: 简
#网站默认语言，1: 繁体中文, 2: 简体中文
defaultEncoding: 1
#延迟时间,若不在前, 要设定延迟翻译时间, 如100表示100ms,默认为0
translateDelay: 0
#博客网址
cookieDomain: "https://jerryc.me/"
#当文字是简体时，按钮显示的文字
msgToTraditionalChinese: "繁"
#当文字是繁体时，按钮显示的文字
msgToSimplifiedChinese: "简"
夜间模式
右下角会有夜间模式按钮
配置 butterfly.yml
YAML# 夜间模式
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 取消自动切换
YAML# 自动切换 dark mode和 light mode
autoChangeMode: false
阅读模式
閲读模式下会去掉除文章外的内容，避免干扰閲读。
只会出现在文章页面，右下角会有閲读模式按钮。
配置 butterfly.yml
YAMLreadmode:
enable: true
侧边设置
可自行决定哪个项目需要显示，可决定位置。（至少需要显示一个）
配置 butterfly.yml
YAMLaside:
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
YAMLbusuanzi:
site_uv: true
site_pv: true
page_pv: true
运行时间
网页已运行时间
配置 butterfly.yml
YAMLruntimeshow:
enable: true
start_date: 2020/2/2 10:00:00
##网页开通时间
#格式: 月/日/年 时间
#也可以写成 年/月/日 时间
标签外挂
Note
移植于 next 主题（注意，书写不是 markdown 规范，而是 hexo 特有的功能，故在其它地方会显示不出效果）
配置 butterfly.yml
YAMLnote:
# 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 相册
MARKDOWN{% gallery %}
markdown 图片格式
{% endgallery %}
例如：
MARKDOWN{% gallery %}
{% endgallery %}
评论
评论我只觉得 Valine 好用。配置遵循 Valine
分享
我选择默认的 Sharejs 就好
搜索系统
Algolia
-
你需要安装 hexo-algolia 或 hexo-algoliasearch. 根据它们的説明文档去做相应的配置。
-
配置
butterfly.ymlYAMLalgolia_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.ymlYAMLlocal_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
YAML# 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:
分析统计
统计找到各个平台找到代码即可
YAMLbaidu_analytics: #百度统计
google_analytics: # 谷歌分析通常以`UA-`打头
tencent_analytics: #腾讯分析
广告
YAMLgoogle_adsense:
enable: true
js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
client: # 填入个人识别码
enable_page_level_ads: true
公式
MathJax
配置 butterfly.yml:
YAMLmathjax:
enable: true
# true 表示每一页都加载mathjax.js
# false 需要时加载，须在使用的Markdown Front-matter 加上 mathjax: true
per_page: false
然后你需要修改一下默认的 markdown 渲染引擎来实现 MathJax 的效果。
查看 https://www.npmjs.com/package/hexo-renderer-kramed
BASHnpm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save
YAMLkramed:
gfm: true
pedantic: false
sanitize: false
tables: true
breaks: true
smartLists: true
smartypants: true
KaTeX (推荐)
首先禁用 MathJax（如果你配置过 MathJax 的话），然后修改你的 butterfly.yml 以便加载 katex.min.css:
YAMLkatex:
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:
YAML# 替换 `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:
YAMLmarkdown_it_plus:
plugins:
- plugin:
name: '@neilsustc/markdown-it-katex'
enable: true
options:
strict: false
美化 / 特效
自定义颜色
配置 butterfly.yml，比如：
颜色值必须被双引号包裹，就像 “#000” 而不是 #000。否则将会在构建的时候报错！
YAMLtheme_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
YAML# 图片格式 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
YAML# footer是否显示图片背景(与top_img一致)
footer_bg: true
打字效果
配置 butterfly.yml
YAML# 打字效果
activate_power_mode:
enable: true
colorful: true # 冒光特效
shake: false # 抖动特效
彩带
参考配置文件
鼠标点击效果
配置 butterfly.yml 文件
-
烟花
YAMLfireworks: enable: true -
爱心
YAMLclick_heart: enable: true -
文字
YAMLClickShowText: enable: false text: - 富强 - 民主 - 文明 - 和谐 - 自由 - 平等 - 公正 - 法治 - 爱国 - 敬业 - 诚信 - 友善 fontSize: 15px
文章页美化
会改变 ol、ul、h1-h5 的样式
配置 butterfly.yml
YAMLpost_beautify:
enable: true
title-prefix-icon: '\f0c1'
title-prefix-icon-color: "#F47466"
title-prefix-icon 填写的是 fontawesome 的 icon 的 Unicode 数
自定义字体
可自行设置字体的 font-family
配置 butterfly.yml
YAMLfont:
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
YAML# 主页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
# (如果有英文逗号' , '，请使用转义字符 ,)
sub:
- 今日事,今日毕
- Never put off till tomorrow what you can do today
主页文章 cover 位置
YAML# 主页文章COVER显示位置
# 三个值可配置 left , right , both
# left(全部图片显示在左边)，right(全部图片显示在右边)，both(左右左右顺序显示)
index_post_cover: left
主页 top_img 显示大小，默认的显示为全屏。site-info 的区域会居中显示
YAML# 主页设置
# 默认top_img全屏，site_info在中间
# 使用默认, 都无需填写（建议默认）
index_top_img_height: #主页top_img高度 例如 300px/300em/300rem 不能使用百分比
注意：index_top_img_height 的值不能使用百分比。
2 个都不填的话，会使用默认值
字数统计
要为 Butterfly 配上字数统计特性，你需要如下几个步骤:
-
打开 hexo 工作目录
-
npm install hexo-wordcount --saveoryarn add hexo-wordcount -
配置
butterfly.yml:YAMLwordcount: 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
YAML# fancybox http://fancyapps.com/fancybox/3/
fancybox:
enable: true
medium_zoom
配置 butterfly.yml
YAMLmedium_zoom:
enable: true
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
