📚 文档目录

🚀 butterfly主题(一)安装部署 - 📌 butterfly主题(二)基本设置 - 🌈 butterfly主题(三)美化

官方主题基础功能设置与相关插件安装，不涉及主题源码修改，不影响主题升级

配置说明

主题版本：Hexo_7.3.0 + Buttrtfly_5.3.5

相关概念：

站点配置文件：./_config.yml
站点配置文件内部链接相对路径：./source/

主题配置文件：./themes/butterfly/_config.yml（./_config.landscape.yml是默认主题配置文件，可删除）
主题配置文件内部链接相对路径：./themes/butterfly/source/

主题配置文件可以重命名为_config.butterfly.yml放到博客根目录，优先级高于主题目录的./themes/butterfly/_config.yml，如果后续主题源码没有较大改动，更新时无需重新配置。

站点配置

修改站点配置文件：./_config.yml，配置站点标题、语言等基础信息

1
2
3
4
5
6
7
8
# Site
title: Xdogの小岛
subtitle: 结束即是开始
description: 是一名独立开发者、博主
keywords:
author: Xdog
language: zh-CN
timezone: ''

主题配置

以下无特殊说明修改的均是主题配置文件_config.butterfly.yml

基本设置

文章锚点

打开文章锚点后，当你滚动文章页面时，文章链接会根据标题ID进行替换，链接会记忆当前阅读位置。

1
2
anchor:
  auto_update: true

默认封面

1
2
3
4
cover:
  default_cover:
    - https://cdn-xdog.oss-cn-hongkong.aliyuncs.com/blog/cover/cover1.webp
    - https://cdn-xdog.oss-cn-hongkong.aliyuncs.com/blog/cover/cover2.webp

首页文章卡片显示标签

1
2
3
post_meta:
  page: # Home Page
    tags: true # true or false 主頁是否顯示標籤

关闭首页文章描述

1
2
index_post_content:
  method: false

文章底部版权提示

1
2
post_copyright:
  decode: true # 链接中文字符不转码

文章底部分享图标

1
2
sharejs:
  sites: wechat,weibo,qq

字数统计

  1. 安装hexo-wordcount
1
npm install hexo-wordcount --save
  1. 修改主题配置文件
1
2
wordcount:
  enable: true

页脚文字

1
2
3
footer:
  owner:
    since: 2021

搜索

本地搜索

文章不多时适用

  1. 安装本地搜索插件
1
npm install hexo-generator-searchdb
  1. 启用本地搜索
1
2
3
4
5
search:
  # Choose: algolia_search / local_search / docsearch
  # leave it empty if you don't need search
  use: local_search
  placeholder:
Algolia搜索

Algolia 是一个在线搜索系统，相较于本地搜索速度大大加快

  1. 先注册账号，然后在 控制台 申请一个香港地区的应用，大概几天后会通过，得到Application ID

  2. 安装hexo-algoliasearch插件

1
npm install hexo-algoliasearch --save
  1. 修改主题配置文件
1
2
3
4
5
search:
  # Choose: algolia_search / local_search / docsearch
  # leave it empty if you don't need search
  use: algolia_search
  placeholder:
  1. 修改站点配置文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
url: https://blog.xdog.top/ # 你的博客地址

algolia:
  appId: "Z7A3XW4R2I" # 申请的 Application ID
  apiKey: "12db1ad54372045549ef465881c17e743" # Search-Only API Key
  adminApiKey: "40321c7c207e7f73b63a19aa24c4761b" # Admin API Key
  chunkSize: 5000
  indexName: "my-hexo-blog" # 应用名
  fields: # 索引列表
    - content:strip:truncate,0,5000 # 内容截取长度，5000代表字数
    - excerpt:strip
    - gallery
    - permalink
    - photos
    - slug
    - tags
    - title
  1. 手动推送索引
1
hexo algolia

这条命令会先编译出静态文件，然后将生成的db.json上传到Algolia

  1. 自动推送索引
    使用Github Action或者Gitlab CI自动完成手动推送步骤
    5.1 在package.json里添加
1
2
3
"scripts": {
  "algolia": "hexo algolia"
},

5.2 在Github Action或者Gitlab CI工作文件里添加

1
2
3
4
script:
  - npm run clean
  - npm run build
  - npm run algolia # 有bug，无法生成db.json文件，需要build命令配合，会重复编译
  1. 自动爬取索引
    要想 Algolia 定期爬取你的网站自动生成索引得在 docsearch.algolia.com 申请，前提网站要有一定内容，太水是通过不了的，不过这个随机区域，不一定能选到香港区域

评论系统

推荐使用 Twikoo Docker私有部署, 响应快，前端有管理界面配置非常方便，防跨域只需要配置好HTTPS即可自动配置完成

  1. Docker 部署
1
docker run --name twikoo -e TWIKOO_THROTTLE=1000 -p 8080:8080 -v ${PWD}/data:/app/data -d imaegoo/twikoo
  1. 部署完成后，开启评论并修改主题配置文件envId为twikoo服务地址即可，注意要为HTTPS协议，否则会被浏览器防跨域拦截
1
2
3
4
5
6
7
8
9
comments:
  use: twikoo
  lazyload: true

twikoo:
  envId: https://twikoo.xdog.top/
  region:
  visitor: false
  option:
  1. 然后hexo s进入评论界面设置账户密码配置即可

如果没有能运行docker的服务器还是推荐使用 Waline，可以使用免费的 Leancloud 数据库，不过配置很麻烦，防跨域也很难配置，不关闭国外的垃圾邮件验证每次发消息都要等个几秒，很让人头大。

关闭favicon图标

1
2
# favicon: /img/favicon.png
favicon:

布局配置

主页文章卡片布局

1
2
3
4
5
6
7
8
9
# 主页文章卡片布局
# 1: 单栏布局，封面在左，信息在右
# 2: 单栏布局，封面在右，信息在左
# 3: 单栏布局，封面和信息左右交替显示
# 4: 单栏布局，封面在上，信息在下
# 5: 单栏布局，信息显示在封面上
# 6: 双栏布局，封面在上，信息在下
# 7: 双栏布局，信息显示在封面上
index_layout: 6

导航栏

修改导航栏目录
修改主题配置文件（格式：页面名字: /路径/ || 图标）
默认图标库：Fontawesome 图标库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Menu 目錄
menu:
  # 主页: / || fas fa-home
  # Archives: /archives/ || fas fa-archive
  # Tags: /tags/ || fas fa-tags
  分类||fas fa-folder-open||hide:
    网站搭建: /categories/网站搭建/
    技术教程: /categories/技术教程/
    休闲娱乐: /categories/休闲娱乐/
  工具||fas fa-tools||hide:
    导航: https://nav.xdog.top/
    云盘: https://pan.xdog.top/
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart

移动端导航栏子目录默认是展开的，如果你想要隐藏，在子目录里添加hide

固定导航栏
修改主题配置文件

1
2
nav:
  fixed: true # fixed navigation bar

固定导航栏后页面位于顶部时仍然透明，和有头图时一致

1
2
3
4
5
6
7
8
9
#page-header.not-top-img:not(.nav-fixed) #nav {
    background: transparent;
    box-shadow: none;
}
#page-header.not-top-img:not(.nav-fixed) #nav a,
#page-header.not-top-img:not(.nav-fixed) #nav .back-home-button,
#page-header.not-top-img:not(.nav-fixed) #nav .site-name {
    color: var(--light-grey);
}

top_img

首页top_img

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

# 打字特效
subtitle:
  enable: true
  sub:
    - 结束即是开始
    - The end is the beginning

归档页top_img

1
archive_img: false

子分类页面和子标签页面top_img

1
2
3
tag_img: false

category_img: false

侧边栏

1
2
3
4
5
6
7
aside:
  card_recent_post:
    enable: false # 1.关闭最近发布
  card_categories:
    enable: false # 2.关闭分类
  card_archives:
    enable: false # 3.关闭归档

关闭busuanzi站点统计，改用 51统计

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

显示网站运行时间

1
2
card_webinfo:
  runtime_date: 2021/06/06

文章侧边栏仅显示目录

1
2
toc:
  style_simple: true # for post

赞助按钮

1
2
3
4
5
6
7
8
9
10
reward:
  enable: false
  text:
  QR_code:
    # - img: /img/wechat.jpg
    #   link:
    #   text: wechat
    # - img: /img/alipay.jpg
    #   link:
    #   text: alipay

文章分页

关闭文章底部上一篇下一篇分页功能

1
post_pagination: false

美化/特效

网站背景

有些人说的”一图流“效果最早我是在 小曳生活馆 看到的，当时就觉得很好看，但是当时对butterfly不熟悉，不知道怎么改，后来出现了一些教程，但还是看不懂。现在终于搞懂了，其实就是放了一张绝对定位的图片，而且实现这个效果完全不用修改主题源码，直接在主题配置文件里就能设置

  1. 修改主题配置文件，配置背景图，成功一半了
1
2
# 建议用深色背景，否则要调整字体颜色
background: https://act.mihoyo.com/zzz/event/e20240528landing-2byyms/images/bg.3b9d20d3..jpg
  1. 修改主题配置文件，把index_img和footer_bg都设为透明
1
2
3
index_img: transparent

footer_img: transparent
  1. 修改主题配置文件，关闭 footer 的黑色半透遮罩，header 关了文章页的也会消失，不能在这里关
1
2
3
mask:
  header: true
  footer: false
  1. 关闭非文章页的 header 黑色半透遮罩
1
2
3
4
.page #page-header:not(.not-top-img):before {
    background-color: transparent;
    backdrop-filter: none;
}
  1. 刷新随机切换背景图片
1
// 不需要，暂时不整
  1. 自用微调
    关于页标题关于我文字颜色固定为白色，如果背景图片不影响其显示效果可以不改
1
2
3
p.p.center {
    color: white;
}

使用图片当网站背景好看是好看，但是图片使用不当就会使某些页面文字看不清，还会影响网站的加载速度，在实用性上不如纯色背景

代码块风格

1
2
3
4
5
6
7
code_blocks:
  # Code block theme: darker / pale night / light / ocean / false
  theme: darker
  macStyle: true
  # Code block height limit (unit: px)
  height_limit: 800
  word_wrap: false

主题颜色

1
2
3
4
theme_color:
  enable: true
  main: "#00c4b6" # 主体色
  blockquote_padding_color: "#00c4b6" # 默认引用块颜色

鼠标点击效果

1
fireworks:

标题图标

1
2
3
beautify:
  enable: true
  title_prefix_icon: \f863 # 标题图标，fontawesome 的图标代号

水平分隔线图标

默认

1
hr_icon:

网站字体

默认

1
2
3
4
5
6
7
8
9
10
11
12
# Global font settings
# Don't modify the following settings unless you know how they work
font:
  global_font_size:
  code_font_size:
  font_family:
  code_font_family:

# Font settings for the site title and site subtitle
blog_title_font:
  font_link:
  font_family:

加载动画

默认

1
preloader:

高级配置

公式

因为我使用公式的场景并不多，所以选择安装相对来说轻量化的 KaTeX

  1. 修改主题配置文件
1
2
3
4
5
6
7
8
math:
  use: katex
  per_page: false # 是否全局加载数学公式渲染引擎，如果设置为 false，则需要在文章的 Front-matter 添加 katex: true
  hide_scrollbar: false

  katex:
    # Enable the copy KaTeX formula
    copy_tex: false
  1. 安装 hexo-renderer-markdown-it 和 katex插件
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 katex @renbaoshuo/markdown-it-katex #需要安装这个katex插件
  1. 修改站点配置文件
1
2
3
markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'

公式格式参考：LaTeX 格式手册 | 洛谷帮助中心

Pjax

点击链接时，pjax会查找链接页面需要替换的部分，然后使用HTML5的pushState局部加载页面，这样可以不用重复加载相同的资源， 从而提升网页的加载速度。

1
2
3
4
5
pjax:
  enable: true
  exclude: # 排除不支持或者不需要 pjax的目录或者文件 
    # - /music/
    # - /no-pjax/

使用pjax后，一些个别页面加载的js/css，将会改为所有页面都加载

由于通过 Pjax 切换的页面并没有完全刷新，浏览器不会将网页从头执行一遍，因此有些 JS 将不会生效，butterfly主题给 JavaScript 代码添加data-pjax属性，可以让其重新加载

主题inject配置处添加data-pjax属性方法：

1
2
3
4
5
inject:
  head:
    # - <link rel="stylesheet" href="/clock/css/clock.css"/>
  bottom:
    - <script data-pjax src="/clock/js/clock.js"></script>

预加载

鼠标滑过链接加载部分页面，点击后加载剩余资源，必开，大幅提升浏览体验，官网

1
instantpage: true

懒加载

1
2
lazyload:
  enable: true

CDN

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
CDN:
  internal_provider: local

  third_party_provider: local

  option:
    egjs_infinitegrid: https://s4.zstatic.net/ajax/libs/egjs-infinitegrid/4.12.0/infinitegrid.min.js
    fancybox: https://lf3-cdn-tos.bytecdntp.com/cdn/expire-1-M/fancybox/3.5.7/jquery.fancybox.min.js
    fancybox_css: https://lf26-cdn-tos.bytecdntp.com/cdn/expire-1-M/fancybox/3.5.7/jquery.fancybox.min.css
    fontawesome: https://s4.zstatic.net/ajax/libs/font-awesome/6.7.2/css/all.min.css
    instantpage: https://s4.zstatic.net/ajax/libs/instant.page/5.2.0/instantpage.min.js
    instantsearch: https://lf26-cdn-tos.bytecdntp.com/cdn/expire-1-M/instantsearch.js/4.39.0/instantsearch.production.min.js
    lazyload: https://lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/vanilla-lazyload/17.3.1/lazyload.iife.min.js
    pjax: https://s4.zstatic.net/ajax/libs/pjax/0.2.8/pjax.min.js
    sharejs: https://lf3-cdn-tos.bytecdntp.com/cdn/expire-1-M/sharer.js/0.5.1/sharer.min.js
    twikoo: https://s4.zstatic.net/ajax/libs/twikoo/1.6.41/twikoo.min.js
    typed: https://lf26-cdn-tos.bytecdntp.com/cdn/expire-1-M/typed.js/2.0.12/typed.min.js

中英文之间添加空格

1
pangu:

开启pjax后会影响主页标题布局

常用插件

永久链接插件

hexo-abbrlink 可使文章拥有唯一永久链接，不会因移动文件位置而改变链接，有利于搜索和分享

  1. 安装
1
npm install hexo-abbrlink --save
  1. 打开站点配置文件，搜索permalink:，替换为以下内容
1
2
3
4
5
permalink: posts/:abbrlink/ # 替换原来的permalink配置
# 加上下面三行
abbrlink:
  alg: crc32 #support crc16(default) and crc32
  rep: dec #support dec(default) and hex

Front Matter需要包含title字段才会自动添加链接

音乐播放器插件

hexo-tag-aplayer 是 APlayer 播放器的Hexo标签插件，可以十分方便地在文章内插入音乐播放器。引入MetingJS后，播放器将支持对于 QQ音乐、网易云音乐、虾米、酷狗、百度等平台的音乐播放。

  1. 安装 hexo-tag-aplayer
1
npm install --save hexo-tag-aplayer
  1. 启用 MetingJS，打开站点配置文件，添加以下内容
1
2
aplayer:
  meting: true  # 启用MetingJS
  1. 修改主题配置文件，启用默认的aplayer/meting的CSS、JS文件
1
2
3
4
# Inject the css and script (aplayer/meting)
aplayerInject:
  enable: true
  per_page: true
  1. 使用

以下为主题默认MetingJS_v1.2版本的使用方法，最新版本使用方法参考 官方文档

参数列表:

选项 默认值 描述
id 必须值 歌曲 id / 播放列表 id / 相册 id / 搜索关键字
server 必须值 音乐平台: netease, tencent, kugou, xiami, baidu
type 必须值 资源类型：song, playlist, album, search, artist
fixed false 开启固定模式
mini false 开启迷你模式
loop all 列表循环模式：all, one,none
order list 列表播放模式： list, random
volume 0.7 播放器音量
lrctype 0 歌词格式类型，有bug，设置为其它值歌词永久关闭，按钮切换显示隐藏失效
listfolded false 指定音乐播放列表是否折叠
storagename metingjs LocalStorage 中存储播放器设定的键名
autoplay true 自动播放，大部分浏览器都不支持此功能
mutex true 该选项开启时，如果同页面有其他 aplayer 播放，该播放器会暂停
listmaxheight 340px 播放列表的最大长度
preload auto 音乐文件预载入模式，可选项： none, metadata, auto
theme #ad7a86 播放器风格色彩设置

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

4.1 局部插入：通过 {% meting ...%} 在文章中使用 MetingJS 播放器

示例：
单首歌曲 (id, server, type)

1
{% meting "1845504308" "netease" "song" %}

歌曲列表

1
{% meting "9288421488" "netease" "playlist" "mutex:false" "listmaxheight:340px" "preload:none" "theme:#ad7a86"%}

4.2 全局插入：修改主题配置文件

1
2
3
4
5
6
7
8
9
# 全局插入
inject:
  head:
  bottom:
    - <div class="aplayer no-destroy" data-id="9288421488" data-server="netease" data-type="playlist" data-fixed="true"> </div>

# 建议开启pjax，防止切换页面音乐中断
pjax:
  enable: true

文章加密插件

hexo-blog-encrypt 是一个 hexo 博客专用的加密插件，支持多种主题

  1. 安装
1
npm install --save hexo-blog-encrypt
  1. 修改站点配置文件
1
2
3
4
5
6
7
8
9
10
# Security
encrypt: # hexo-blog-encrypt
  abstract: 有东西被加密了, 请输入密码查看.
  message: 您好, 这里需要密码.
  tags:
  - {name: tagName, password: 密码A}
  - {name: tagName, password: 密码B}
  theme: Flip
  wrong_pass_message: 抱歉, 这个密码看着不太对, 请再试试.
  wrong_hash_message: 抱歉, 这个文章不能被校验, 不过您还是能看看解密后的内容.
  1. 使用
    在文章front matter填上password字段即可加密，例
1
2
3
4
5
---
title: Hello World
date: 2016-03-30 21:18:02
password: hello
---

进阶配置

跳过渲染

Hexo默认会对/source/里的所有页面应用主题模板渲染，但有一些前端作品或demo页我们不希望经过渲染，而是能保持完全自定义的样子

方法一：在 Front Matter 里加入以下代码

1
2
3
---
layout: false
---

方法二：修改站点配置文件_config.yml
找到skip_render字段，配置需要跳过渲染的文件或者目录，注意文件或者目录要放在source目录下
示例：

1
2
3
4
5
6
7
8
9
10
# 不渲染 source/test.html
skip_render: test.html
# 不渲染 source/test 目录下的所有文件
skip_render: test/*
# 不渲染 source/test 目录下的所有文件包括子文件夹以及子文件夹内的文件
skip_render: test/**
# 多文件目录写法
skip_render:
  - text.html
  - text/*

修改了配置但生成出来的内容不一定及时应用了新配置，最好在生成之前执行一下hexo clean命令，清除掉旧的生成文件和缓存。

设置完成后通过https://xdog.top/test/就能访问了

注意：通过https://xdog.top/test/访问，index.html引用资源的相对路径是相对于/test目录的；
而通过https://xdog.top/test访问，index.html引用资源的相对路径是相对于/source目录的。
想要两种方式都能访问只能以链接的方式引用资源文件

Qexo 后台

Qexo 是一个静态博客编辑器，使静态博客也能像动态博客一样通过网页发布文章。

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

打开主题配置文件，搜索post_edit:

1
2
3
4
5
post_edit:
  enable: true
  # 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: https://github.com/pbloods/pbloods.github.io/edit/master/source/