📚 文档目录

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

博主的主题配置，基于Hexo_8.0+Buttrtfly_5.5.2，更多请查阅 Butterfly 文档

配置文件

Hexo配置文件：./_config.yml（Hexo配置文件内部链接相对路径：./source/）
主题配置文件：./themes/butterfly/_config.yml（主题配置文件内部链接相对路径：./themes/butterfly/source/）

将主题配置文件重命名为_config.butterfly.yml，放在博客根目录也会生效，且优先级高于主题目录的./themes/butterfly/_config.yml。下面教程若无额外说明默认修改的都是主题配置文件_config.butterfly.yml。

CDN

主题使用的部分第三方CDN在大陆无法访问，必须更换为大陆可用的CDN

1
2
3
4
5
6
7
8
9
CDN:
  option:
    fontawesome: https://s4.zstatic.net/ajax/libs/font-awesome/7.0.1/css/all.min.css # 默认字体图标
    egjs_infinitegrid: https://s4.zstatic.net/ajax/libs/egjs-infinitegrid/4.12.0/infinitegrid.min.js # 瀑布流布局依赖
    sharejs: https://s4.zstatic.net/ajax/libs/social-share.js/1.0.16/js/social-share.min.js # 文章分享
    sharejs_css: https://s4.zstatic.net/ajax/libs/social-share.js/1.0.16/css/share.min.css # 文章分享
    typed: https://s4.zstatic.net/ajax/libs/typed.js/2.1.0/typed.umd.js # 首页打字特效
    pjax: https://s4.zstatic.net/ajax/libs/pjax/0.2.8/pjax.min.js # 局部加载
    instantpage: https://s4.zstatic.net/ajax/libs/instant.page/5.2.0/instantpage.min.js # 预加载

推荐

备选

网站资料

站点标题、作者等信息，修改 Hexo 配置文件：./_config.yml

1
2
3
4
5
6
7
8
# Site
title: Xdogの小岛 # 站点标题
subtitle: 结束即是开始 # 站点副标题
description: 是一名独立开发者、博主 # 作者卡片描述
keywords:
author: Xdog # 作者卡片名称
language: zh-CN # 设置站点语言为中文
timezone: ''

页脚建站时间

1
2
3
footer:
  owner:
    since: 2021

图片设置

浏览器标签图标

1
favicon: /img/favicon.ico

侧边栏博主卡片头像

1
2
3
avatar:
  img: /img/butterfly-icon.png
  effect: false # 是否旋转

文章默认封面

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

top_img

1
2
3
4
5
6
7
8
# 归档页top_img
archive_img: false

# 子分类页面top_img
tag_img: false

# 子标签页面top_img
category_img: false

导航栏

修改导航栏目录（格式：页面名字: /路径/ || 图标，默认图标库：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

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

首页瀑布流文章卡片布局

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

首页文章卡片显示标签

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

关闭首页文章卡片描述

1
2
index_post_content:
  method: false

文章页

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

1
2
anchor:
  auto_update: true

文章底部版权提示

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

关闭文章底部分享功能

1
2
3
4
share:
  # Choose: sharejs / addtoany
  # Leave it empty if you don't need share
  use:

文章字数统计

1
2
3
# npm install hexo-wordcount --save
wordcount:
  enable: true

文章页侧边栏仅显示目录

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

侧边栏

关闭最近发布、分类、归档卡片

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站点统计

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

网站运行时间

1
2
card_webinfo:
  runtime_date: 2021/06/06

美化/特效

一图流

固定背景图片，不随鼠标滑动

  1. 配置背景图，建议用深色背景，否则要调整字体颜色
1
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
2
3
beautify:
  enable: true
  title_prefix_icon: \f863 # 标题图标，fontawesome 的图标代号

搜索

本地搜索

安装本地搜索插件

1
npm install hexo-generator-searchdb

修改主题配置文件

1
2
3
search:
  use: local_search
  placeholder: false

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

自动推送索引：使用Github Action或者Gitlab CI自动完成手动推送步骤
在package.json里添加

1
2
3
"scripts": {
  "algolia": "hexo algolia"
},

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

1
2
3
4
script:
  - npm run clean
  - npm run build
  - npm run algolia # 有bug，无法生成db.json文件，需要build命令配合，会重复编译

自动爬取索引
要想 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 数据库，不过配置很麻烦，防跨域也很难配置，不关闭国外的垃圾邮件验证每次发消息都要等个几秒，很让人头大。

拓展配置

公式

由于使用公式场景不多，因此选择轻量化的 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局部加载页面，这样可以不用重复加载相同的资源， 从而提升网页的加载速度，使用pjax后，一些个别页面加载的js/css，将会改为所有页面都加载。

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

Pjax 生效后，切换页面时某些 JavaScript 代码不会重新执行，给代码添加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

永久链接

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 播放器风格色彩设置

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

1
2
3
4
5
# 单首歌曲 (id, server, type)
{% meting "1845504308" "netease" "song" %}

# 歌曲列表
{% 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默认会对/source/里的所有页面应用主题模板渲染，但有一些前端作品或demo页我们不希望经过渲染，而是能保持完全自定义的样子

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

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

方法二：修改站点配置文件
找到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/*

设置完成后通过https://xxx.com/test/访问，引用资源的默认路径是/test目录