Butterfly 安装文档(四) 主题配置-2
📖 本教程更新于 2022 年 10 月 21 日,教程的内容针对最新稳定版而更新(如果你是旧版,教程会有些出入,请留意)
🦋 Butterfly 已经更新到 4.5.0
📚 文档目录
🚀 快速开始📑 主题页面🛠 主题配置-1⚔️ 主题配置-2❓ 主题问答⚡️ 进阶教程自定义代码配色添加全局吸底 Aplayer 教程自定义侧边栏标签外挂 (Tag Plugins)内置标签外挂Markdown Style testCode Highlight Style test个性化配置
你可以通过右下角的 简 按钮切换为简体显示
评论
从3.0.0开始,开启评论需要在comments-use
中填写你需要的评论。
支持双评论显示,只需要配置两个评论(第一个为默认显示)
1 | comments: |
参数 | 解释 |
---|---|
use | 使用的评论(请注意,最多支持两个,如果不需要请留空) 注意:双评论不能是 Disqus 和 Disqusjs 一起,由于其共用同一个 ID,会出错 |
text | 是否显示评论服务商的名字 |
lazyload | 是否为评论开启lazyload,开启后,只有滚动到评论位置时才会加载评论所需要的资源(开启 lazyload 后,评论数将不显示) |
count | 是否在文章顶部显示评论数 livere、Giscus 和 utterances 不支持评论数显示 |
card_post_count | 是否在首页文章卡片显示评论数 gitalk、livere 、Giscus 和 utterances 不支持评论数显示 |
单评论
双评论
显示text
不显示text
与Disqus一样,但由于Disqus在中国大陆无法访问, 使用Disqusjs可以在无法访问Disqus时显示评论。具体可参考Disqusjs。
修改 主题配置文件
1 | disqusjs: |
当无法访问 Disqus 时,会显示
遵循 gitalk的指示去获取你的 github Oauth 应用的 client id 和 secret 值。以及查看它的相关配置説明。
然后修改 主题配置文件
:
1 | gitalk: |
遵循 Valine的指示去配置你的 LeanCloud 应用。以及查看相应的配置説明。
然后修改 主题配置文件
:
1 | valine: |
开启 visitor 后,文章页的访问人数将改为 Valine 提供,而不是 不蒜子
Valine于 v1.4.5 开始支持自定义表情,如果你需要自行配置,请在emojiCDN
配置表情 CDN。
同时在Hexo 工作目录下的source/_data/
创建一个json文件valine.json
,等同于 Valine 需要配置的emojiMaps
,valine.json
配置方式可参考如下
valine.json
1 | { |
default_avatar
参数 | 效果 |
---|---|
留空(默认) | |
mp | |
identicon | |
monsterid | |
wavatar | |
retro | |
robohash | |
blank | |
404 |
Waline - 一款从 Valine 衍生的带后端评论系统。可以将 Waline 等价成 With backend Valine。
具体配置可参考 waline 文档
然后修改 主题配置文件
:
1 | waline: |
开启 pageview 后,文章页的访问人数将改为 Waline 提供,而不是 不蒜子
与Gitalk一样,基于 GitHub issues 的评论工具。相对于Gitalk,其相对需要权限较少。具体配置可参考Utterances。
修改 主题配置文件
:
1 | utterances: |
Facebook Comments
是Facebook提供的评论插件,需要登陆Facebook才可评论。
修改 主题配置文件
1 | # Facebook Comments Plugin |
Twikoo
是一个简洁、安全、无后端的静态网站评论系统,基于腾讯云开发。
具体如何配置评论,请查看 Twikoo文档
你只需要把获取到的 环境ID (envId)
填写到配置上去就行
修改 主题配置文件
1 | twikoo: |
参数 | 解释 |
---|---|
envId | 环境 ID |
region | 环境地域,默认为 ap-shanghai,如果您的环境地域不是上海,需传此参数 |
visitor | 是否显示文章阅读数 |
option | 可选配置 |
开启 visitor 后,文章页的访问人数将改为 Twikoo 提供,而不是 不蒜子
一个基于 GitHub Discussions 的评论
1 | # Giscus |
具体配置的意思,请参考 Giscus 的文档
remark42 是一款只支持私有部署的评论
具体部署请查看 Installation | Remark42
1 | remark42: |
在綫聊天
从3.0开始,Butterfly主题内置了多种在綫聊天工具。你可以选择开启一种,方便你与访客的交流。
这些工具都提供了一个按钮可以打开/关闭聊天窗口。
主题也提供了一个集合主题特色的按钮来替换这些工具本身的按钮,这个聊天按钮将会出现在右下角里。
你只需要把chat_btn
打开就行。
修改 主题配置文件
1 | # Chat Button [recommend] |
为了不影响访客的体验,主题提供一个chat_hide_show
配置
设为true
后,使用工具提供的按钮时,只有向上滚动才会显示聊天按钮,向下滚动时会隐藏按钮。
修改 主题配置文件
1 | # The origin chat button is displayed when scrolling up, and the button is hidden when scrolling down |
如果使用工具自带的聊天按钮,按钮位置可能会遮挡右下角图标,请配置rightside-bottom
调正右下角图标位置
配置chatra,需要知道Public key
打开chatra并注册账号。
你可以在Preferences
中找到Public key
修改 主题配置文件
1 | # chatra |
chatra
的样式你可以Chat Widget
自行配置
Demo
配置tidio,需要知道Public key
打开tidio并注册账号。
你可以在Preferences > Developer
中找到Public key
修改 主题配置文件
1 | # tidio |
tidio
的样式你可以Channels
自行配置
Demo
打开daovoice和注册帐号
找到你的app id
修改 主题配置文件
1 | # daovoice |
可在聊天设置
里配置聊天按钮等样式
Demo
打开Gitter和注册账号
创建一个community
或者room
,复制名称到设置去
修改 主题配置文件
1 | # gitter |
Demo
打开crisp并注册帐号
找到需要的网站ID
1 | # crisp |
messenger 为 Facebook 旗下的聊天服务
具体操作请查看 Facebook 洽谈附加程式 - Messenger 平台
1 | messenger: |
分享
只能选择一个分享服务商
搜索系统
记得运行 hexo clean
如果你使用 hexo-algoliasearch,请记得配置 fields 参数的
title
,permalink
和content
你需要安装 hexo-algolia或 hexo-algoliasearch. 根据它们的説明文档去做相应的配置。
修改
主题配置文件
1 | algolia_search: |
记得运行 hexo clean
你需要安装 hexo-generator-search,根据它的文档去做相应配置
修改
主题配置文件
1 | local_search: |
参数 | 解释 |
---|---|
enable | 是否开启本地搜索 |
preload | 预加载,开启后,进入网页后会自动加载搜索文件。关闭时,只有点击搜索按钮后,才会加载搜索文件 |
CDN | 搜索文件的 CDN 地址(默认使用的本地链接) |
网站验证
如果需要搜索引擎收录网站,可能需要登录对应搜索引擎的管理平台进行提交。
各自的验证码可从各自管理平台拿到
修改 主题配置文件
1 | site_verification: |
分析统计
广告
主题已集成谷歌广告(自动广告)
修改 主题配置文件
1 | google_adsense: |
主题预留了三个位置可供插入广告,分别为主页文章(每三篇文章出现广告)/aside公告之后/文章页打赏之后。
把html代码填写到对应的位置
修改 主题配置文件
1 | ad: |
例如:
1 | index: <ins class="adsbygoogle" style="display:block" data-ad-format="fluid" data-ad-layout-key="xxxxxxxxxxxx" data-ad-client="ca-pub-xxxxxxxxxx" data-ad-slot="xxxxxxxxxx"></ins><script>(adsbygoogle=window.adsbygoogle||[]).push({})</script> |
Math 数学
不要在标题里使用 mathjax 语法,toc 目录不一定能正确显示 mathjax,可能显示 mathjax 代码
建议使用 KaTex 获得更好的效果,下文有介绍!
修改 主题配置文件
:
1 | mathjax: |
如果
per_page
设为true
,则每一页都会加载 Mathjax 服务。设为false
,则需要在文章Front-matter
添加mathjax: true
,对应的文章才会加载 Mathjax 服务。
然后你需要修改一下默认的 markdown
渲染引擎来实现 MathJax 的效果。
以下操作在你 hexo 博客的目录下 (不是 Butterfly 的目录):
安装插件
1
2npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save配置 hexo 根目录的配置文件
1
2
3
4
5
6
7
8kramed:
gfm: true
pedantic: false
sanitize: false
tables: true
breaks: true
smartLists: true
smartypants: true
效果:
不要在标题里使用 KaTeX 语法,toc 目录不能正确显示 KaTeX。
首先禁用MathJax
(如果你配置过 MathJax 的话),然后修改你的主题配置文件
以便加载katex.min.css
:
1 | katex: |
你不需要添加 katex.min.js
来渲染数学方程。相应的你需要卸载你之前的 hexo 的 markdown 渲染器,然后安装其它插件。
卸载掉 marked 插件,安装 hexo-renderer-markdown-it
1 | npm un hexo-renderer-marked --save # 如果有安装这个的话,卸载 |
在 hexo 的根目录的 _config.yml
中配置
1 | markdown: |
如需配置其它参数,请参考 katex 官网
注意,此方法生成的 katex 没有斜体
卸载掉 marked 插件,然后安装新的hexo-renderer-markdown-it-plus
:
1 | # 替换 `hexo-renderer-kramed` 或者 `hexo-renderer-marked` 等hexo的markdown渲染器 |
注意到 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:
1 | markdown_it_plus: |
当然,你还可以利用这个特性来定义一些自己常用的 macros
。
因为 KaTeX 更快更轻量,因此没有 MathJax 的功能多(比如右键菜单)。为那些使用 MathJax 的用户,主题也内置了 katex 的 复制 功能。
美化/特效
自定义主题色
可以修改大部分UI颜色
修改 主题配置文件
,比如:
颜色值必须被双引号包裹,就像
"#000"
而不是#000
。否则将会在构建的时候报错!
1 | theme_color: |
网站背景
默认显示白色,可设置图片或者颜色
修改 主题配置文件
1 | # 图片格式 url(http://xxxxxx.com/xxx.jpg) |
留意: 如果你的网站根目录不是’/‘,使用本地图片时,需加上你的根目录。
例如:网站是 https://yoursite.com/blog
,引用一张img/xx.png
图片,则设置background为 `url(/blog/img/xx.png)
background:’#49B202’
background: url(https://i.loli.net/2019/09/09/5oDRkWVKctx2b6A.png)
footer 背景
修改 主题配置文件
1 | # footer是否显示图片背景(与top_img一致) |
配置的值 | 效果 |
---|---|
留空/false | 显示默认的顔色 |
img链接 | 图片的链接,显示所配置的图片 |
顔色( HEX值 - #0000FF RGB值 - rgb(0,0,255) 顔色单词 - orange 渐变色 - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%) ) |
对应的顔色 |
true | 显示跟 top_img 一样 |
true
打字效果
修改 主题配置文件
1 | # Typewriter Effect (打字效果) |
背景特效
好看的綵带背景,可设置每次刷新更换綵带,或者每次点击更换綵带
修改 主题配置文件
1 | canvas_ribbon: |
相关配置可查看canvas_ribbon
好看的綵带背景,会飘动
修改 主题配置文件
1 | canvas_fluttering_ribbon: |
修改 主题配置文件
1 | canvas_nest: |
鼠标点击效果
zIndex
建议只在-1
和9999
上选-1
代表烟火效果在底部9999
代表烟火效果在前面
修改 主题配置文件
1 | fireworks: |
修改 主题配置文件
1 | # 点击出现爱心 |
修改 主题配置文件
1 | # 点击出现文字,文字可自行修改 |
页面美化
会改变ol、ul、h1-h5的样式
field
配置生效的区域
post
只在文章页生效site
在全站生效
修改 主题配置文件
1 | # 美化页面显示 |
title-prefix-icon
填写的是fontawesome的icon的Unicode数。
未开启美化
开启美化
自定义字体和字体大小
全局字体
可自行设置字体的font-family
如不需要配置,请留空
修改 主题配置文件
1 | # Global font settings |
Blog 标题字体
可自行设置字体的font-family
如不需要配置,请留空。
如不需要使用网络字体,只需要把font_link留空就行
修改 主题配置文件
1 | # Font settings for the site title and site subtitle |
网站副标题
可设置主页中显示的网站副标题或者喜欢的座右铭。
修改 主题配置文件
1 | # 主页subtitle |
主页top_img显示大小
适用于 版本号 >= V1.2.0
默认的显示为全屏。site-info的区域会居中显示
1 | # 主页设置 |
注意:index_top_img_height
的值不能使用百分比。
2个都不填的话,会使用默认值
举例,当
1 | index_top_img_height: 400px |
效果
页面加载动画 preloader
当进入网页时,因为加载速度的问题,可能会导致 top_img 图片出现断层显示,或者网页加载不全而出现等待时间,开启preloader后,会显示加载动画,等页面加载完,加载动画会消失。
主题支持 pace.js 的加载动画,具体可查看 pace.js
配置 butterly.yml
1 | # 加载动画 Loading Animation |
fullpage-loading
PWA
要为Butterfly
配上 PWA 特性, 你需要如下几个步骤:
打开 hexo 工作目录
npm install hexo-offline --save
或者yarn add hexo-offline
在根目录创建
hexo-offline.config.cjs
文件,并增加以下内容。
1 | // offline config passed to workbox-build. |
更多内容请查看 hexo-offline的官方文档
- 在
主题配置文件
中开启 pwa 选项。
1 | pwa: |
- 在创建
source/
目录中创建manifest.json
文件。
1 | { |
你也可以通过 Web App Manifest快速创建manifest.json
。(Web App Manifest 要求至少包含一个 512*512 像素的图标)
- 可以通过
Chrome
插件Lighthouse
检查 PWA 配置是否生效以及配置是否正确。- 打开博客页面
- 启动
Lighthouse
插件 (Lighthouse
插件要求至少包含一个 512*512 像素的图标)
关于 PWA(渐进式增强 Web 应用)的更多内容请参阅 Google Tools for Web Developers
字数统计
要为Butterfly
配上字数统计特性, 你需要如下几个步骤:
打开 hexo 工作目录
npm install hexo-wordcount --save
oryarn add hexo-wordcount
修改
主题配置文件
:
1 | wordcount: |
图片大图查看模式
只能开启一个
如果你并不想为某张图片添加大图查看模式,你可以使用 html 格式引用图片,併为图片添加 no-lightbox
class 名。
修改 主题配置文件
1 | # fancybox http://fancyapps.com/fancybox/3/ |
修改 主题配置文件
1 | medium_zoom: true |
Snackbar 弹窗
Snackbar 弹窗,根据自己爱好开启
修改 主题配置文件
1 | # Snackbar 弹窗 |
未开启Snackbar
开启Snackbar
其它配置
CSS 前缀
有些 CSS 并不是所有浏览器都支持,需要增加对应的前缀才会生效。
开启 css_prefix
后,会自动为一些 CSS 增加前缀。(会增加 20%的体积)
修改配置文件
1 | # Add the vendor prefixes to ensure compatibility |
Open Graph
在 head
里增加一些 meta 资料,例如缩略图、标题、时间等等。当你分享网页到一些平台时,平台会读取 Open Graph 的内容,展示缩略图,标题等等信息。
修改配置文件
1 | # Open graph meta tags |
Instantpage
当鼠标悬停到链接上超过 65 毫秒时,Instantpage 会对该链接进行预加载,可以提升访问速度。
修改配置文件
1 | # https://instant.page/ |
Pangu
如果你跟我一样,每次看到网页上的中文字和英文、数字、符号挤在一块,就会坐立难安,忍不住想在它们之间加个空格。这个外挂正是你在网路世界走跳所需要的东西,它会自动替你在网页中所有的中文字和半形的英文、数字、符号之间插入空白。
修改配置文件
1 | # https://github.com/vinta/pangu.js |
field
只支持两个参数,post
(只在文章页生效)和site
(全站生效)
Pjax
当用户点击链接,通过ajax更新页面需要变化的部分,然后使用HTML5的pushState修改浏览器的URL地址。
这样可以不用重複加载相同的资源(css/js), 从而提升网页的加载速度。
1 | # Pjax [Beta] |
对于一些第三方插件,有些并不支持 pjax 。
你可以把网页加入到 exclude
里,这个网页会被 pjax 排除在外。
点击该网页会重新加载网站
使用pjax后,一些自己DIY的js可能会无效,跳转页面时需要重新调用,请参考Pjax文档
使用pjax后,一些个别页面加载的js/css,将会改为所有页面都加载
Butterfly的Pjax目前仍有一些问题,请留意
- 使用谷歌广告可能会报错(例如自动广告)
如果你在使用中发现问题,欢迎反馈Bugs
Inject
2.3.0以上支持
如想添加额外的js/css/meta等等东西,可以在Inject里添加,支持添加到head(</body>
标签之前)和bottom(</html>
标签之前)。
请注意:以标准的html格式添加内容
例如
1 | inject: |
留意: 如果你的网站根目录不是’/‘,使用本地图片时,需加上你的根目录。
例如:网站是 https://yoursite.com/blog
,引用css/xx.css
,则设置为<link rel="stylesheet" href="/blog/css/xx.css">
CDN
配置文件中最后一部分CDN,里面是主题所引用到的文件,可自行配置CDN。(非必要请勿修改,配置后请确认链接是否能访问)
1 | CDN: |
参数 | 解释 |
---|---|
internal_provider | 主题内部文件 可选 local/jsdelivr/unpkg/cdnjs/custom lcoal 为本地加载,custom 为自定义格式,需配置 custom_format 注意: 如果使用的是 Dev 版,只能设置为 local |
third_party_provider | 第三方文件 可选 local/jsdelivr/unpkg/cdnjs/custom lcoal 为本地加载,custom 为自定义格式,需配置 custom_format 注意: 如果你选择 local 需要安装 hexo-butterfly-extjs 插件 |
version | true/false 为 cdn 加上指定版本号 |
custom_format | 自定义格式 |
option | 你可以在这里更换部分文件,会覆盖原有的配置 |
version
如需修改版本号,可修改主题目录
的 ‘plugins.yml’ 中对应插件的 version
请确保你修改的版本号,你所使用的 cdn 有收录
custom_format
提供以下参数
参数 | 解释 |
---|---|
name | npm 上的包名 |
file | npm 上的文件路径 |
min_file | npm 上的文件路径(压缩过的文件) |
cdnjs_name | cdnjs 上的包名 |
cdnjs_file | cdnjs 上的文件路径 |
min_cdnjs_file | cdnjs 上的文件路径(压缩过的文件) |
version | 插件版本号 |
部分可用的第三方 CDN 列表
❓ Butterfly 安装文档(五) 主题问答请确保你选择的 CDN 有收录主题使用的第三方插件