hexo魔改教程(二)
博客搭建与魔改系列教程导航🚥🚥🚥
- hexo基础教程(一)
- hexo魔改教程(一)
- hexo魔改教程(二)
- hexo魔改教程(三)
- hexo魔改教程(四)
- hexo魔改教程(五)
- hexo魔改教程(六)
- 综合美化模块教程
本篇是第 11 ~ 20 个魔改,适用Hexo 8.1.2+Butterfly 5.7.2。
阅读约定:每个代码块上方都标了 文件 和 改法。[Blogroot] 指博客根目录;「新建文件」是建好文件后整段写入,「追加到末尾」是放到文件最后,「替换」是在已有文件里改对应位置。配置片段都写清了是站点 _config.yml 还是主题 _config.butterfly.yml,照抄前先确认文件里有没有同名键。
昼夜切换按钮(带日月动画)
借鉴:店长(Fomalhaut 整理)。本站改动:SVG 与切换逻辑并入本站主题注入,按钮样式按导航栏尺寸调整。
昼夜切换按钮
新建 [Blogroot]\themes\butterfly\layout\includes\custom\sun_moon.pug,写入:
文件:[Blogroot]/themes/butterfly/layout/includes/custom/sun_moon.pug | 改法:新建文件,整段写入;主题里若已有同名文件,用这段内容整体覆盖。
1 | svg(aria-hidden='true', style='position:absolute; overflow:hidden; width:0; height:0') |
新建 [Blogroot]\themes\butterfly\source\js\sun_moon.js,写入:
文件:[Blogroot]/themes/butterfly/source/js/sun_moon.js | 改法:新建文件,整段写入;本主题自带同名文件时整体覆盖,不要两段并存。
1 | function btfSwitchTheme(toDark) { |
新建 [Blogroot]\themes\butterfly\source\css\_layout\sun_moon.styl,写入:
文件:[Blogroot]/themes/butterfly/source/css/_layout/sun_moon.styl | 改法:新建文件,整段写入;已有则整体覆盖。必须放在主题 source/css/_layout/ 下,才会被主题编译进 index.css。
1 | .Cuteen_DarkSky, |
在 [Blogroot]\themes\butterfly\layout\includes\head.pug 最末尾添加:
文件:[Blogroot]/themes/butterfly/layout/includes/head.pug | 改法:追加到文件末尾;前两行若已存在(主题原文件就有),只补最后一行 include ./custom/sun_moon.pug。
1 | !=fragment_cache('injectHead', function(){return injectHtml(theme.inject.head)}) |
在 [Blogroot]\themes\butterfly\layout\includes\header\nav.pug 的 #menus 块之后添加(缩进 2 格,与 #menus 同级):
文件:[Blogroot]/themes/butterfly/layout/includes/header/nav.pug | 改法:在 #menus 块之后插入,保持 2 格缩进,与 #menus 同级。
1 | //- 暗黑模式按钮 |
把 [Blogroot]\themes\butterfly\layout\includes\rightside.pug 的 when 'darkmode' 分支改成:
文件:[Blogroot]/themes/butterfly/layout/includes/rightside.pug | 改法:替换 mixin rightsideItem 里 when 'darkmode' 的整个分支(连同下面注释掉的旧按钮)。
1 | when 'darkmode' |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml(主题配置,不是站点 _config.yml)| 改法:display_mode 改顶层原值;darkmode 找到同名顶层键后整块替换。
1 | display_mode: light |
在 [Blogroot]\_config.butterfly.yml 的 inject.bottom 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:只把 <script> 这一行追加到已有 inject: bottom: 列表末尾;inject: / bottom: 键文件里已经有了,照抄会重复键导致 YAML 报错。
1 | inject: |
导航栏「美化设置」按钮
借鉴:Fomalhaut(猕猴桃)。本站改动:图标与按钮位置按本站导航栏重排,面板入口与美化设置联动。
美化设置按钮
把阿里图标库导出的 JS 放到 [Blogroot]\source\js\ali_font.js,其中要有 #icon-tupian1 这个 symbol。
在 [Blogroot]\themes\butterfly\layout\includes\header\nav.pug 的 #menus 块之后添加:
文件:[Blogroot]/themes/butterfly/layout/includes/header/nav.pug | 改法:紧接上一节的昼夜按钮,在 #menus 块之后插入,2 格缩进。
1 | //- 美化设置 |
新建 [Blogroot]\source\js\meihua.js,写入:
文件:[Blogroot]/source/js/meihua.js | 改法:新建文件,整段写入(放站点 source/js/,别放主题目录,升级主题不会丢)。
1 | function toggleWinbox() { |
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。本站 custom.css 已经由 inject.head 的 <link> 引入,不用再加一行。
1 | #meihua-winbox { |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:在已有的 tag_plugins: 块里给 CDN: 加 iconfont: 一行;本站该行目前是注释状态,要用时取消注释。
1 | tag_plugins: |
在 [Blogroot]\_config.butterfly.yml 的 inject.bottom 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:只把 <script> 这一行追加到已有 inject: bottom: 列表,别重复写 inject: / bottom:。
1 | inject: |
导航栏挤不下才切三条杠
借鉴:Fomalhaut(猕猴桃)。本站改动:宽度测量与断点按本站导航项重新调整。
导航栏自适应
新建 [Blogroot]\source\js\nav-fit.js,写入:
文件:[Blogroot]/source/js/nav-fit.js | 改法:新建文件,整段写入;站点已有同名文件就整段覆盖。
1 | (function () { |
在 [Blogroot]\_config.butterfly.yml 的 inject.bottom 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:追加到已有 inject: bottom: 列表末尾。
1 | inject: |
[Blogroot]\_config.butterfly.yml 的 menu 分组写法:
文件:[Blogroot]/_config.butterfly.yml | 改法:替换 menu: 下对应分组的写法;|| hide: 是让桌面导航隐藏子菜单、只在手机菜单里出现。
1 | menu: |
文章页顶部波浪
借鉴:安知鱼(Fomalhaut 整理)。本站改动:Pug 插入位置按 5.7.2 调整,波浪配色接本站背景遮罩。
文章页波浪
在 [Blogroot]\themes\butterfly\layout\includes\header\index.pug 的 include ./post-info.pug 后面插入:
文件:[Blogroot]/themes/butterfly/layout/includes/header/index.pug | 改法:把 include ./post-info.pug 那一段换成下面这块(缩进保持 4 格),波浪就只在文章页出现。
1 | if globalPageType === 'post' |
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | .main-hero-waves-area { width: 100%; position: absolute; left: 0; bottom: -11px; z-index: 5; } |
自定义全屏加载动画
借鉴:安知鱼(Fomalhaut 整理)。本站改动:加载模板按 5.7.2 重写,结束逻辑与本站
PJAX流程对齐。
自定义加载动画
把 [Blogroot]\themes\butterfly\layout\includes\loading\fullpage-loading.pug 整个替换为:
文件:[Blogroot]/themes/butterfly/layout/includes/loading/fullpage-loading.pug | 改法:整段替换整个文件(主题自带,改前先备份)。
1 | #loading-box(onclick='document.getElementById("loading-box").classList.add("loaded")') |
把 [Blogroot]\themes\butterfly\source\css\_layout\loading.styl 整个替换为:
文件:[Blogroot]/themes/butterfly/source/css/_layout/loading.styl | 改法:整段替换整个文件(主题自带,改前先备份)。
1 | if hexo-config('preloader') |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:找到顶层 preloader: 键,改 enable / source / pace_css_url 三个值。source 要和模板对应:1 才是上面替换的整页加载模板,2 是 pace 进度条(本站现在用 2)。
1 | preloader: |
打赏按钮投币特效
借鉴:店长(Fomalhaut 整理)。本站改动:模板按 5.7.2 结构重写,打赏图片与文案换成本站配置。
打赏投币
把 [Blogroot]\themes\butterfly\layout\includes\post\reward.pug 整个替换为:
文件:[Blogroot]/themes/butterfly/layout/includes/post/reward.pug | 改法:整段替换整个文件;模板读的是 theme.CDN.option.coin_css、coin_js 和 theme.reward.QR_code,配置没配就是空链接。
1 | link(rel='stylesheet' href=url_for(theme.CDN.option.coin_css) media="defer" onload="this.media='all'") |
新建 [Blogroot]\source\css\coin.css,写入:
文件:[Blogroot]/source/css/coin.css | 改法:新建文件,整段写入;站点已有同名文件(完整版投币样式)就保留原文件,不要覆盖。
1 | .tip-button { position: relative; border: 0; background: none; cursor: pointer; } |
新建 [Blogroot]\source\js\coin.js,写入:
文件:[Blogroot]/source/js/coin.js | 改法:新建文件,整段写入;本站 source/js/coin.js 已有另一版(.tip-button 点击触发 coinAudio()),已有就保留原版。
1 | document.addEventListener('click', function (e) { |
把收款码图片放到 [Blogroot]\source\img\,音效放到 [Blogroot]\source\audio\coin.mp3。
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:coin_js / coin_css 写到已有的 CDN: option: 下;reward: 是顶层键,整块替换(本站 reward.enable 目前是 false,要出按钮得改成 true)。
1 | CDN: |
右下角「直达底部」与右键模式
借鉴:Leonus、Fomalhaut(猕猴桃)。本站改动:两个按钮按 5.7.2 右侧栏结构合并,图标与配色跟本站右侧按钮统一。
右下角按钮
在 [Blogroot]\themes\butterfly\layout\includes\rightside.pug 的 mixin rightsideItem(array) 里,在 when 'comment' 分支后面添加:
文件:[Blogroot]/themes/butterfly/layout/includes/rightside.pug | 改法:在 mixin rightsideItem 的 when 'comment' 分支后插入 when 'mouse';代码块里的 when 'comment' 只是定位用,原文件已有,别重复粘贴。
1 | when 'comment' |
把同一文件的默认隐藏数组改成:
文件:[Blogroot]/themes/butterfly/layout/includes/rightside.pug | 改法:替换文件里 - const hideArray = ... 那一行,数组里加上 'mouse'。
1 | - const hideArray = enable && hide ? hide.split(',') : ['readmode','translate','darkmode','hideAside', 'mouse'] |
在同一文件 button#go-up 后面添加:
文件:[Blogroot]/themes/butterfly/layout/includes/rightside.pug | 改法:在 button#go-up 后面插入;代码块前半段是已有的 go-up,只加 go-down 那三行,别整段粘。
1 | button#go-up(type="button" title=_p("rightside.back_to_top")) |
同一文件 when 'darkmode' 分支用第 11 项的日月 SVG。changeMouseMode() 由第 6 项的 source/js/rightmenu.js 提供。
音乐馆独立页面
借鉴:安知鱼(Fomalhaut 整理)。本站改动:页面分支与标题判断按 5.7.2 重写,音乐页接入本站歌单。
音乐馆页面
在 [Blogroot]\themes\butterfly\layout\page.pug 的 case page.type 里添加分支:
文件:[Blogroot]/themes/butterfly/layout/page.pug | 改法:在 case page.type 里加 when 'music' 分支;when 'categories' 那几行是定位用,原文件已有。
1 | when 'categories' |
把同一文件的页面标题判断改成:
文件:[Blogroot]/themes/butterfly/layout/page.pug | 改法:替换原来那行标题判断,多一个 page.type != 'music' 条件,音乐页不显示大标题。
1 | if top_img === false && page.type != 'music' && page.title |
新建 [Blogroot]\themes\butterfly\layout\includes\page\music.pug,写入:
文件:[Blogroot]/themes/butterfly/layout/includes/page/music.pug | 改法:新建文件,整段写入;主题已有同名文件就只改 meting-js 的 id(歌单 ID)。
1 | #anMusic-page |
新建 [Blogroot]\source\music\index.md,写入:
文件:[Blogroot]/source/music/index.md | 改法:新建文件,整段写入;本站已有同名页面(自建音乐网格,front matter 里没有 type: music),要用主题音乐馆模板才补这一行。
1 | --- |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 aplayerInject: 键已存在,改 enable / per_page 两个值即可。
1 | aplayerInject: |
在 [Blogroot]\_config.butterfly.yml 的 inject.head 和 inject.bottom 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:两行分别追加到已有 inject: head: 和 inject: bottom: 列表,别重复写 inject:;本站这两行现在是注释状态,启用前确认 source/css/music.css 和 source/js/anzhiyu.js 都在。
1 | inject: |
自定义 404 页面
自定义 404
新建 [Blogroot]\themes\butterfly\source\404.html,写入:
文件:[Blogroot]/themes/butterfly/source/404.html | 改法:新建文件,整段写入;主题 source/ 下的文件会被原样拷到 public/404.html。
1 |
|
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:替换已有 error_404: 块的值;enable: false 才用上面自己写的静态 404.html,改成 true 会由主题模板生成同路径页面,两个抢同一个文件。
1 | error_404: |
节日弹窗与农历计算
借鉴:Fomalhaut(猕猴桃)。本站改动:弹窗队列与
Sweetalert2改为本地加载,节日文案按本站配置。
节日弹窗
把 Sweetalert2 官方压缩版放到 [Blogroot]\source\js\sweetalert2.all.js。
新建 [Blogroot]\source\js\day.js,写入:
文件:[Blogroot]/source/js/day.js | 改法:新建文件,整段写入;站点已有同名文件就整段覆盖。
1 | (function () { |
农历节日需要时把农历库放到 [Blogroot]\source\js\lunar.js,并在 day.js 之前引入。
在 [Blogroot]\_config.butterfly.yml 的 inject.bottom 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:两行追加到已有 inject: bottom: 列表;lunar.js 必须排在 day.js 前面。
1 | inject: |
改完怎么验证与部署
十节改完先别急着上传,本地按顺序走一遍:
- 生成:在博客根目录执行
hexo generate(或hexo g)。最后一行出现Generated且没有 Pug / Stylus 报错才算过;改过主题模板后报错,多半是缩进或include路径写错。 - 本地预览:执行
hexo server(或hexo s),打开http://localhost:4000,逐项点到:昼夜切换按钮、美化设置按钮、导航栏宽度、文章页波浪、加载动画、打赏投币、右下角按钮、/music/、随便敲一个不存在的地址看 404、节日弹窗。 - 强制刷新或清缓存:改过 CSS / JS 后按
Ctrl + F5;装了 Service Worker 的再加一步,DevTools → Application → Service Workers 勾Update on reload或点Unregister后刷新,否则看到的还是旧文件。 - F12 查 404:Console 里不该有
Uncaught;Network 里sun_moon.js、meihua.js、nav-fit.js、coin.js、day.js应是 200。变成 404 基本就是注入路径和文件位置对不上——/js/xxx.js对应source/js/xxx.js,/css/xxx.css对应source/css/xxx.css。 - 上传
public/:按原来的托管方式发布:Nginx 把public/同步到站点根目录,GitHub Pages 推public/或走 Actions,Vercel 连仓库自动构建,用hexo deploy的再跑一次hexo deploy。上线后换无痕窗口再验一遍,确认线上和本地一致。
还有一条要记住:themes/butterfly/ 里的改动不会跟着主题升级保留,升级前先把自己改过的模板文件备份出来。
