hexo-butterfly-基础操作

hahah

发布于 2022-06-14 21:20:01

2.8K00

代码可运行

文章被收录于专栏：爪哇学习日记爪哇学习日记

运行总次数：0

代码可运行

更新记录

2021-01-01

基于hexo-butterfly的基本操作

hexo-butterfly-基础操作

1.hexo-butterfly样式美化

基本配置信息可参考“博客项目基本操作”文档说明进行配置，此处针对一些个性化设置做简单配置说明

具体配置详情可参考官方文档说明：https://butterfly.js.org/posts/4aa8abbe/

主题页面

Front-matter概念

Front-matter 是 markdown 文件最上方以 —- 分隔的區域，用於指定個別檔案的變數。

Page Front-matter 用於頁面配置；Post Front-matter 用於文章頁配置

可在scaffolds模板中自定义配置相关参数，

# Page Front-matter 用于页面配置
title				【必需】頁面標題
date				【必需】頁面創建日期
type				【必需】標籤、分類和友情鏈接三個頁面需要配置
updated			【可選】頁面更新日期
description	【可選】頁面描述
keywords		【可選】頁面關鍵字
comments		【可選】顯示頁面評論模塊(默認 true)
top_img			【可選】頁面頂部圖片
mathjax			【可選】顯示mathjax(當設置mathjax的per_page: false時，才需要配置，默認 false)
katex				【可選】顯示katex(當設置katex的per_page: false時，才需要配置，默認 false)
aside				【可選】顯示側邊欄 (默認 true)
aplayer			【可選】在需要的頁面加載aplayer的js和css,請參考文章下面的音樂 配置
highlight_shrink	【可選】配置代碼框是否展開(true/false)(默認為設置中highlight_shrink的配置)

# Post Front-matter 用于文章页配置
title							【必需】文章標題
date							【必需】文章創建日期
updated						【可選】文章更新日期
tags							【可選】文章標籤
categories				【可選】文章分類
keywords					【可選】文章關鍵字
description				【可選】文章描述
top_img						【可選】文章頂部圖片
cover							【可選】文章縮略圖(如果沒有設置top_img,文章頁頂部將顯示縮略圖，可設為false/圖片地址/留空)
comments					【可選】顯示文章評論模塊(默認 true)
toc								【可選】顯示文章TOC(默認為設置中toc的enable配置)
toc_number				【可選】顯示toc_number(默認為設置中toc的number配置)
copyright					【可選】顯示文章版權模塊(默認為設置中post_copyright的enable配置)
copyright_author	【可選】文章版權模塊的文章作者
copyright_author_href	【可選】文章版權模塊的文章作者鏈接
copyright_url					【可選】文章版權模塊的文章連結鏈接
copyright_info				【可選】文章版權模塊的版權聲明文字
mathjax								【可選】顯示mathjax(當設置mathjax的per_page: false時，才需要配置，默認 false)
katex									【可選】顯示katex(當設置katex的per_page: false時，才需要配置，默認 false)
aplayer								【可選】在需要的頁面加載aplayer的js和css,請參考文章下面的音樂 配置
highlight_shrink			【可選】配置代碼框是否展開(true/false)(默認為設置中highlight_shrink的配置)
aside									【可選】顯示側邊欄 (默認 true)

标签&分类&友情链接

具体分类&标签应用参考魔改攻略说明，友情链接创建的思路也是大同小异，具体说明如下所示

<1>分类&标签

对应导航栏、文章的关联配置，具体参考魔改攻略说明

<2>友情链接

创建友情链接主页

# 进入博客项目根目录，执行指令生成标签页信息
hexo new page link

# 上述指令执行完成在source下生成link目录（内有index.md为友情链接页），修改index.md文件
在front-matter中添加type: "link" 内容

友情链接添加

# 在hexo博客根目录中的source/_data(如无可自行创建),创建一个link.yml文件，对应内容如下所示
- class_name: 友情鏈接
  class_desc: 那些人，那些事
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、簡單且強大的網誌框架

- class_name: 網站
  class_desc: 值得推薦的網站
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: 視頻網站
    - name: Weibo
      link: https://www.weibo.com/
      avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
      descr: 中國最大社交分享平台
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: 社交分享平台

友情链接界面设置

自2.2.0起，友情链接界面可通过用户自定义，在友情链接的md档进行设置（支持markdown格式）

测试结果如下所示，具体可结合自身需求调整

图库

图库页面是一个普通的页面挂在图片信息概念，具体构建如下所示

# 创建图库页面，相应在menu中引入测试
hexo new page entertainment

# 在source/entertainment/index.md文件中：使用标签外挂galleryGroup
<div class="gallery-group-main">
{% galleryGroup '壁紙' '收藏的一些壁紙' '/Gallery/wallpaper' https://i.loli.net/2019/11/10/T7Mu8Aod3egmC4Q.png %}
{% galleryGroup '漫威' '關於漫威的圖片' '/Gallery/marvel' https://i.loli.net/2019/12/25/8t97aVlp4hgyBGu.jpg %}
{% galleryGroup 'OH MY GIRL' '關於OH MY GIRL的圖片' '/Gallery/ohmygirl' https://i.loli.net/2019/12/25/hOqbQ3BIwa6KWpo.jpg %}
</div>

测试结果如下所示

子页面

以此类推，子頁面也可当做普通页面处理

# 创建子页面
hexo new page daily

# 在指定source/daily/index.md文件中外挂gallery
{% gallery %}
![](https://i.loli.net/2019/12/25/Fze9jchtnyJXMHN.jpg)
![](https://i.loli.net/2019/12/25/ryLVePaqkYm4TEK.jpg)
![](https://i.loli.net/2019/12/25/gEy5Zc1Ai6VuO4N.jpg)
![](https://i.loli.net/2019/12/25/d6QHbytlSYO4FBG.jpg)
![](https://i.loli.net/2019/12/25/6nepIJ1xTgufatZ.jpg)
![](https://i.loli.net/2019/12/25/E7Jvr4eIPwUNmzq.jpg)
![](https://i.loli.net/2019/12/25/mh19anwBSWIkGlH.jpg)
![](https://i.loli.net/2019/12/25/2tu9JC8ewpBFagv.jpg)
{% endgallery %}

测试结果如下所示

404页面

主题_config.yml配置文件_config.butterfly.yml，查看404配置

# A simple 404 page
error_404:
  enable: true # 默认false
  subtitle: 'Page Not Found' # 页面子标题
  background: https://i.loli.net/2020/05/19/aKOcLiyPl2JQdFD.png # 页面背景图

配置完成，展示页面

基础美化

子标题

subtitle:
  enable: true
  # Typewriter Effect (打字效果)
  effect: true
  # loop (循環打字)
  loop: true
  # source 調用第三方服務
  # source: false 關閉調用
  # source: 1  調用一言網的一句話（簡體） https://hitokoto.cn/
  # source: 2  調用一句網（簡體） http://yijuzhan.com/
  # source: 3  調用今日詩詞（簡體） https://www.jinrishici.com/
  # subtitle 會先顯示 source , 再顯示 sub 的內容
  source: false
  # 如果關閉打字效果，subtitle 只會顯示 sub 的第一行文字
  sub:
    - title...

代码

highlight_theme: mac light # 高亮 darker / pale night / light / ocean / mac / mac light / false
highlight_copy: true # 复制按钮控制
highlight_lang: true # 代码语言展示
highlight_shrink: false # 代码框展开/关闭:true-不展开、有>按钮/false-展开、有>按钮/none-不显示>按钮
highlight_height_limit: 200 # unit: px (default:false)  # 代码高度限制3.7.0及以上支持
code_word_wrap: false # 代码换行

社交图标

social:
  fab fa-github: https://github.com/xxxxx || Github
  fas fa-envelope: mailto:xxxxxx@gmail.com || Email

主页文章节选（自动节选和文章页description）

由于主题UI限制，主页文章节选支持自动节选、文章页

1 description： 只顯示description
2 both： 優先選擇description，如果沒有配置description，則顯示自動節選的內容
3 auto_excerpt：只顯示自動節選
4 false： 不顯示文章內容

index_post_content:
  method: 3
  length: 500 # if you set method to 2 or 3, the length need to config

description则在相应的md文档中的Front-matter中添加

Front-matter 是md文件最上方以 ‘—-‘ 分隔的区域，用于指定个别文件的变量

---
	title: 文档标题
	tags:
		- Java
		- DB
	categories: Java
	keywords: 'Java,Java'
	description: 文档描述
	cover: 
	abbrlink:
	date:
	top_img:
---

顶部图

# 顶部图禁用配置
disable_top_img: false

# 顶部图启用可配置下述参数
index_img	# 主页的top_img
default_top_img # 默认top_img，当页面的top_img没有配置则显示default_top_img
archive_img	# 归档页面的top_img(对应archive)

tag_img	tag # tag子页面默认的top_img
tag_per_img	tag # tag子页面的top_img，可配置每個tag的top_img

category_img	category # category子页面的默认top_img
category_per_img	category # category子页面的top_img，可配置每個category的top_img

# 针对单个tag、category配置说明（不建议为每个分类、标签配置不同的顶部图，会拖慢生成速度，且相应需一一对应）
tag_per_img:
  aplayer: https://xxxxxx.png
  android: ddddddd.png
  
category_per_img:
  分类1: hdhdh.png
  分类2: ddjdjdjd.png

# 其他页面配置：top_img配置说明如下(在指定的md文件中的front-matter设定)
其它頁面（tags/categories/自建頁面）和文章页的top_img ，在对应的md文件中设置front-matter中的top_img
top_img: orange # 纯色
top_img: 'linear-gradient(20deg, #0062be, #925696, #cc426e, #fb0347)' # 渐变
top_img:false # 取消指定文章顶部图

参考配置针对相关资源的引用，不建议把项目所需的文件或者资源放在主题下的source文件夹下，伴随着主题的迭代升级会将里面的内容覆盖掉，因此需要在项目根目录下的source文件夹下创建文件夹存放资源数据

# 1.图片资源引入
方式1:将图片资源放置在hexo项目根目录/themes/指定主题文件夹/source/img文件夹下(可自定义分类)
方式2:在博客项目根目录的source文件夹下创建文件夹resources存放资源信息，分类存储资源（推荐）
访问方式:source/folderName/filename 对应路径配置:/folderName/filename 即可

# 2.在主题配置文件中通过/img/文件名称.png方式引入
archive_img: /resources/img/banner01.png

tag_img: /resources/img/banner01.png
tag_per_img: # 针对常见标签进行设定
	# 技术栈划分 
  java: /resources/img/tag-top-img/java.jpg
  android: /resources/img/tag-top-img/android.jpg
  python: /resources/img/tag-top-img/python.jpg
  php: /resources/img/tag-top-img/php.jpg
  oracle: /resources/img/tag-top-img/oracle.jpg
  mysql: /resources/img/tag-top-img/mysql.jpg
  mongoDB: /resources/img/tag-top-img/mongoDB.jpg
  redis: /resources/img/tag-top-img/redis.jpg
  html: /resources/img/tag-top-img/html.jpg
  css: /resources/img/tag-top-img/css.jpg
  javascript: /resources/img/tag-top-img/javascript.jpg
  linux: /resources/img/tag-top-img/linux.jpg
  
  # 领域方向相关
  前端: /resources/img/tag-top-img/front-end.jpg
  后端: /resources/img/tag-top-img/back-end.jpg
  大数据: /resources/img/tag-top-img/bigdata.jpg
 
  数据库: /resources/img/tag-top-img/database.jpg
  数据结构: /resources/img/tag-top-img/data-structure.jpg
  网络: /resources/img/tag-top-img/network.jpg
  
  系统设计: /resources/img/tag-top-img/se.jpg
  软件工程: /resources/img/tag-top-img/se.jpg
  分布式: /resources/img/tag-top-img/se.jpg

category_img: /resources/img/banner01.png
category_per_img:
  文章: /resources/img/banner01.png
  分类: /resources/img/banner01.png

文章封面

cover:
  # 是否顯示文章封面
  index_enable: true
  aside_enable: true
  archives_enable: true
  # 封面顯示的位置(left-统一居左 , right-统一居右 , both-一左一右交互)
  position: both
  # 當沒有設置cover時，默認的封面顯示(可指定一或多个)
  default_cover: 
		- /resources/img/cover/cover01.jpg
		- /resources/img/cover/cover02.jpg
		- /resources/img/cover/cover03.jpg
		- /resources/img/cover/cover04.jpg
		- /resources/img/cover/cover05.jpg
		- /resources/img/cover/cover06.jpg
		- /resources/img/cover/cover07.jpg
		- /resources/img/cover/cover08.jpg
		- /resources/img/cover/cover09.jpg
		- /resources/img/cover/cover10.jpg
		- /resources/img/cover/cover11.jpg
		- /resources/img/cover/cover12.jpg
		- /resources/img/cover/cover13.jpg
		- /resources/img/cover/cover14.jpg
		
# 在博客项目根目录/source/img中引入cover相关图片资源

文章页相关配置

<1>文章meta显示

用于显示文章相关信息

post_meta:
  page:
    date_type: both # created or updated or both 主頁文章日期是創建日或者更新日或都顯示
    date_format: relative # date/relative 顯示日期還是相對日期
    categories: true # true or false 主頁是否顯示分類
    tags: true # true or false 主頁是否顯示標籤
    label: true # true or false 顯示描述性文字
  post:
    date_type: both # created or updated or both 文章頁日期是創建日或者更新日或都顯示
    date_format: relative # date/relative 顯示日期還是相對日期
    categories: true # true or false 文章頁是否顯示分類
    tags: true # true or false 文章頁是否顯示標籤
    label: true # true or false 顯示描述性文字

<2>文章版权、许可协议

post_copyright:
  enable: true
  decode: false
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

# 從3.0.0開始，支持對單獨文章設置版權信息，可以在文章中Front-matter單獨設置版权显示信息
copyright_author: xxxx
copyright_author_href: https://xxxxxx.com
copyright_url: https://xxxxxx.com
copyright_info: 此文章版權歸xxxxx所有，如有轉載，請註明來自原作者

<3>文章打赏

在你每篇文章的結尾，可以添加打賞按鈕。可配置二维码，若没有配置二维码，可提供icon图片在link相应的链接（link不写默认为图片链接）

修改主題配置文件_config.butterfly.yml

reward:
  enable: true
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: 微信
    - img: /img/alipay.jpg
      link:
      text: 支付寶

<4>TOC（文章目录）

修改主題配置文件_config.butterfly.yml

toc:
  post: true # 文章页是否显示目录
  page: false # 主页是否显示目录
  number: true # 是否显示章节数
  expand: false
  style_simple: false # for post

为特定文章配置

在文章中的front-matter中指定toc_number、toc参数为true或者false，主题优先判断文章内的配置，随后参考主题配置文件中的配置

<5>相关文章

相关文章推荐的原理是根据文章tags的比重进行推荐

修改主題配置文件_config.butterfly.yml

related_post:
  enable: true
  limit: 6 # Number of posts displayed
  date_type: created # or created or updated 文章日期顯示創建日或者更新日

<6>文章锚点

当开启文章锚点，当在文章页进行滚动，文章连接根据标题ID进行替换（每替换一次会留下相应的历史记录，如果文章如果有很多锚点，网页历史记录会很多）

修改主題配置文件_config.butterfly.yml

anchor: false # 默认false

<7>文章过期提醒

设置是否显示文章过期提醒

修改主題配置文件_config.butterfly.yml

# Displays outdated notice for a post (文章過期提醒)
noticeOutdate:
  enable: false
  style: flat # style: simple/flat
  limit_day: 500 # 距离更新时间多少天才显示文章过期提醒
  position: top # position: top/bottom
  message_prev: It has been # 天数之前的文字
  message_next: days since the last update, the content of the article may be outdated. # 天数之后的文字

<8>文章编辑按钮

文章标题旁显示编辑按钮，点击则跳转到对应的链接

修改主題配置文件_config.butterfly.yml

post_edit:
  enable: false
  # url: https://github.com/user-name/repo-name/edit/branch-name/subdirectory-name/

<9>文章分页按钮

设置分类逻辑，也可关闭显示

修改主題配置文件_config.butterfly.yml

# post_pagination (分頁)
# value: 1 || 2 || false
# 1: 下一篇显示的是旧文章
# 2: 下一篇显示的是新文章
# false: 关闭分页按钮
post_pagination: false

头像

修改主題配置文件_config.butterfly.yml

# Avatar (頭像)
avatar:
  img: /resources/img/profile-photo/avatar.png # 默认/img/avatar.png
  effect: true # 头像会一直转圈

图片描述

修改主題配置文件_config.butterfly.yml

# figcaption (圖片描述文字)
photofigcaption: false

复制相关配置

修改主題配置文件_config.butterfly.yml

# 配置网站是否可以直接复制，复制的内容是否添加版权信息
# copyright: Add the copyright information after copied content (複製的內容後面加上版權信息)
copy:
  enable: true # 是否开启网站复制权限
  copyright: # 复制的内容后面加上版权信息相关的配置
    enable: true # 是否开启复制版权信息添加
    limit_count: 50 # 字数限制，当复制内容超出该字数限制则在复制的内容后加入版权信息

Footer设置

修改主題配置文件_config.butterfly.yml

footer:
  owner:
    enable: true
    since: 2021 # 博客年份配置
  custom_text: Hi, welcome to holic-x <a href="https://butterfly.js.org/">blog 新的一年，一起学习一起进步</a>! # 页脚自定义文本
  copyright: true # Copyright of theme and framework
  
# 针对custom_text页脚自定义文本也可设定ICP，参考如下
custom_text: <a href="icp鏈接"><img class="icp-icon" src="icp圖片"><span>備案號：xxxxxx</span></a>

右下角按钮

<1>简繁转化

修改主題配置文件_config.butterfly.yml

translate:
  enable: true
  # 默認按鈕顯示文字(網站是簡體，應設置為'default: 繁')
  default: 簡
  #網站默認語言，1: 繁體中文, 2: 簡體中文
  defaultEncoding: 1
  #延遲時間,若不在前, 要設定延遲翻譯時間, 如100表示100ms,默認為0
  translateDelay: 0
  #當文字是簡體時，按鈕顯示的文字
  msgToTraditionalChinese: "繁"
  #當文字是繁體時，按鈕顯示的文字
  msgToSimplifiedChinese: "簡"

<2>夜间模式

修改主題配置文件_config.butterfly.yml

darkmode:
  enable: true
  # dark mode和 light mode切換按鈕
  button: true
  # v2.0.0新增选项用于dark、light模式自动切换：1-随着系统变化，不支持的浏览器/系统则按照晚上6点-早上6点切换为dark；2-只按照时间，晚上6点-早上6点切换为dark其余时间为light；false：取消自动切换
  autoChangeMode: false

<3>阅读模式

阅读模式下去除文章外的内容，避免干扰阅读，出现在文章页面右下角（阅读模式按钮）

修改主題配置文件_config.butterfly.yml

# Read Mode (閲讀模式)
readmode: true

侧边栏设置

<1>侧边排版

可自行决定哪个项目需要展示、位置、隐藏等

修改主題配置文件_config.butterfly.yml

aside:
  enable: true
  hide: false
  button: true # aside 按钮控制:开启或隐藏
  mobile: true # 手機頁面（ 顯示寬度 < 768px ）是否顯示aside內容
  position: right # 侧边栏位置:left or right 
  card_author: # 作者栏控制
    enable: true
    description:
    button:
      enable: true
	  icon: fab fa-github
      text: Github
      link: https://github.com/jerryc127/hexo-theme-butterfly
  card_announcement: # 公告栏
    enable: true
    content: 新的一年，一起学习，一起进步~
  card_recent_post: # 最近发布的文章
    enable: true
    limit: 5 # if set 0 will show all
    sort: date # date or updated
  card_categories: # 分类栏控制
    enable: true
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
  card_tags:  # 标签栏控制
    enable: true
    limit: 40 # if set 0 will show all
    color: true # 标签颜色控制
  card_archives: # 文章栏控制
    enable: true
    type: monthly # yearly or monthly
    format: MMMM YYYY # eg: YYYY年MM月
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending
    limit: 8 # if set 0 will show all
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true

<2>访问人数

修改主題配置文件_config.butterfly.yml

busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

不蒜子：http://busuanzi.ibruce.info/

<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_site_pv">本站总访问量<span id="busuanzi_value_site_pv"></span>次</span>

<3>运行时间

修改主題配置文件_config.butterfly.yml

runtimeshow:
  enable: true
  publish_date: 01/01/2021 00:00:00 # 月/日/年 时间 或 年/月/日 时间

<4>最新评论

修改主題配置文件_config.butterfly.yml

3.1.0起支持，最新评论只有在刷新的时候才读取（非实时变化），由于API访问次数限制，为了避免调用太多，主题默认存取期限为10分钟，即调用后资料会存储在localStorage中，10分钟内刷新网站会去localStorage中读取资料，10分钟期限过去后再次刷新页面才会调用API读取新的数据（3.6.0新增storage配置，可自行设定配置缓存时间）

# 最新评论区展示
newest_comments:
  enable: true 
  sort_order: # Don't modify the setting unless you know how it works
  limit: 6
  storage: 10 # unit: mins, save data to localStorage
  avatar: true # 是否显示头像

<5>自定义侧边栏

适用于>=3.8.0

参考链接：https://butterfly.js.org/posts/ea33ab97/

自定义widget参考步骤

在hexo博客项目根目录source/_data文件夹中创建widget.yml文件，格式参考如下所示

top:
  - class_name: # 【可选】所创建的widget父类class名
    id_name:    # 【可选】所创建的widget父类id名
    name:       # 【可选】所创建的widget标题
    icon:       # 【可选】所创建的widget图标
    html:       # 【可选】所创建的widget相关代码

bottom:
  - class_name:
    id_name:
    name:
    icon:
    order:       # 【可选】所创建的widget排序
    html:

以网站资讯侧边栏为例，说明如下

对应代码生成参考如下：

<div class="card-widget 所寫的 class_name" id="所寫的 id_name" style="order: 所寫的 order">
    <div class="item-headline">
        <i class="所寫的 icon"></i>
        <span>所寫的 name</span>
    </div>
    <div class="item-content">
        所寫的 html
    </div>
</div>

“访客地图案例说明”

a.获取访客地图的html代码

<script type="text/javascript" id="clstr_globe" src="//clustrmaps.com/globe.js?d=5V2tOKp8qAdRM-i8eu7ETTO9ugt5uKbbG-U7Yj8uMl8"></script>

b.创建widget.yml文件

bottom:
    - class_name: user-map
      id_name: user-map
      name: 访客地图
      icon: fas fa-heartbeat
      order:
      html: '<script type="text/javascript" id="clstr_globe" src="//clustrmaps.com/globe.js?d=5V2tOKp8qAdRM-i8eu7ETTO9ugt5uKbbG-U7Yj8uMl8"></script>'

c.运行hexo项目，查看结果

标签外挂

标签外挂仅限于butterfly主题，可以为主题带来额外的功能和UI方面的优化，但是也会有相应的限制（在使用的时候需要相应注意），注意相应主题版本

<1>Note(Bootstrap Callout)

适用于next主题并进行修改

# 主题配置文件修改
note:
  # 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: false
  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

用法1：

{% note [class] [no-icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}

名称	用法
class	【可选】标识（不同标识有不同配色）（ default / primary / success / info / warning / danger ）
no-icon	【可选】不显示icon
style	【可选】可以覆盖配置中的style（simple/modern/flat/disabled）

用法2：自定义icon（3.2.0以上版本支持）

{% note [color] [icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}

名称	用法
color	【可选】颜色(default / blue / pink / red / purple / orange / green)
icon	【可选】可配置自定义icon（只支持fontawesome图标，也可配置no-icon）
style	【可选】可以覆盖配置中的style（simple/modern/flat/disabled）

<2>Gallery相册图库

2.0.0 以上提供

<div class="gallery-group-main">
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
</div>

name:图库名字
description:图库描述
link:链接相册地址
img-url:图库地址

<3>Gallery相册

2.0.0 以上提供

{% gallery %}
markdown 圖片格式
![图片描述](url链接)
{% endgallery %}

<4>tag-hide：文字标签隐藏

2.2.0以上提供

hideInline：隐藏文字信息，点击按钮后触发展示( content不能包含英文逗號，可用‚)

{% hideInline content,display,bg,color %}

block：独立的隐藏内容（点击后显示）

{% hideBlock display,bg,color %}
content
{% endhideBlock %}

参数	说明
content	文本内容
display	【可选】按钮显示的文字
bg	【可选】按钮背景颜色
color	【可选】按钮文字颜色

<5>hideToggle：收缩框

构建参考

{% hideToggle display,bg,color %}
content
{% endhideToggle %}

# 参数配置说明
content: 文本内容
display: 显示的文字 (可选)
bg: 背景颜色 (可选)
color: 文字的颜色 (可选)

# 构建标签内容
<div class="hide-toggle">
	<div class="hide-button toggle-title" style="">
    <i class="fa fa-caret-right fa-fw"></i>
    <span>文字</span>
  </div>
  <div class="hide-content">
    <p>默认效果</p>
  </div>
</div>

<6>mermaid：图形绘制

使用mermaid标签可以绘制Flowchart（流程圖）、Sequence diagram（時序圖）、Class Diagram（類別圖）、State Diagram（狀態圖）、Gantt（甘特圖）和Pie Chart（圓形圖）

mermaid文档参考：https://mermaid-js.github.io/mermaid/#/

配置主题配置文件

# mermaid
# see https://github.com/mermaid-js/mermaid
mermaid:
  enable: true
  # built-in themes: default/forest/dark/neutral
  theme:
    light: default
    dark: dark

案例测试：具体参考mermaid文档

// 格式
{% mermaid %}
內容
{% endmermaid %}

饼状图构建

{% mermaid %}
pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5
{% endmermaid %}

<7>Tabs：标签页

构建语法：

{% tabs Unique name, [index] %}
<!-- tab [Tab caption] [@icon] -->
Any content (support inline tags too).
<!-- endtab -->
{% endtabs %}

Unique name   : Unique name of tabs block tag without comma.
                Will be used in #id's as prefix for each tab with their index numbers.
                If there are whitespaces in name, for generate #id all whitespaces will replaced by dashes.
                Only for current url of post/page must be unique!
[index]       : Index number of active tab.
                If not specified, first tab (1) will be selected.
                If index is -1, no tab will be selected. It's will be something like spoiler.
                Optional parameter.
[Tab caption] : Caption of current tab.
                If not caption specified, unique name with tab index suffix will be used as caption of tab.
                If not caption specified, but specified icon, caption will empty.
                Optional parameter.
[@icon]       : FontAwesome icon name (full-name, look like 'fas fa-font')
                Can be specified with or without space; e.g. 'Tab caption @icon' similar to 'Tab caption@icon'.
                Optional parameter.

案例1：预设选择第一个默认

{% tabs test1 %} 
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

案例2：预设选择tabs

{% tabs test2, 3 %}
标签页面内容不变

案例3：没有预设值

{% tabs test3, -1 %}
标签页面内容不变

案例3：没有预设值

{% tabs test4 %}
<!-- tab 第一個Tab -->
**tab名字為第一個Tab**
<!-- endtab -->

<!-- tab @fab fa-apple-pay -->
**只有圖標 沒有Tab名字**
<!-- endtab -->

<!-- tab 炸彈@fas fa-bomb -->
**名字+icon**
<!-- endtab -->
{% endtabs %}

<8>Button：按钮

3.0 以上适用

{% btn [url],[text],[icon],[color] [style] [layout] [position] [size] %}

[url]         : 鏈接
[text]        : 按鈕文字
[icon]        : [可選] 圖標
[color]       : [可選] 按鈕背景顔色(默認style時）
                      按鈕字體和邊框顔色(outline時)
                      default/blue/pink/red/purple/orange/green
[style]       : [可選] 按鈕樣式 默認實心
                      outline/留空
[layout]      : [可選] 按鈕佈局 默認為line
                      block/留空
[position]    : [可選] 按鈕位置 前提是設置了layout為block 默認為左邊
                      center/right/留空
[size]        : [可選] 按鈕大小
                      larger/留空

<9>inlineImg：内联展示图片

{% inlineImg [src] [height] %}

[src]      :    圖片鏈接
[height]   ：   圖片高度限制【可選】

举例说明

markdown语法:![](url)
{% inlineImg url 150px %}

<10>label：高亮所需文字

3.7.5及以上版本适用

{% label text color %}
text:文字
clolr:【可选】背景颜色，默认为default(default/blue/pink/red/purple/orange/green)

<11>timeline：时间线

4.0.0以上支持

{% timeline title,color %}
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
{% endtimeline %}

参数	说明
title	标题/时间线
color	timeline颜色default(留空) / blue / pink / red / purple / orange / green

美化/特效

下述操作如无特殊说明，在主题配置文件修改_config.butterfly.yml

自定义主题色

下述配置默认全部注释，如果需要自定义主题色则解开注释相应进行配置即可

theme_color:
  enable: true
  main: "#49B1F5"
  paginator: "#00c4b6"
  button_hover: "#FF7242"
  text_selection: "#00c4b6"
  link_color: "#99a9bf"
  meta_color: "#858585"
  hr_color: "#A4D8FA"
  code_foreground: "#F47466"
  code_background: "rgba(27, 31, 35, .05)"
  toc_color: "#00c4b6"
  blockquote_padding_color: "#49b1f5"
  blockquote_background_color: "#49b1f5"
  scrollbar_color: "#49b1f5"

网站背景

可设定图片或者颜色

background:

# 图片路径引用说明
网络资源路径：url(http://xxxxxx.com/xxx.jpg)
background: url(https://i.loli.net/2019/09/09/5oDRkWVKctx2b6A.png)

相对路径引用：如果网站根目录不是/，则使用本地图片需要填充加上根目录信息，例如网站是 https://yoursite.com/blog,引用一张img/xx.png图片，则设置background为 `url(/blog/img/xx.png)

# 背景颜色设定
background: '#49B202'

footer背景

可设定是否显示footer背景

# 留空/false:显示默认的颜色、img显示链接、true：与top_img一致
footer_bg: true

# img链接

# 颜色值设定
顔色(
	HEX值 - #0000FF
	RGB值 - rgb(0,0,255)
	顔色单词 - orange
	渐变色 - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%)
）

打字效果

# Typewriter Effect (打字效果)
# https://github.com/disjukr/activate-power-mode
activate_power_mode:
  enable: true
  colorful: true # open particle animation (冒光特效)
  shake: true #  open shake (抖动特效)
  mobile: false

背景特效

静止彩带、动态彩带、canvas-nest

# 静止彩带（每次刷新或者点击的时候更换彩带）
# 参考：https://github.com/hustcc/ribbon.js
canvas_ribbon:
  enable: false
  size: 150
  alpha: 0.6
  zIndex: -1
  click_to_change: false  #设置是否每次点击都更换綵带
  mobile: false # false 手机端不显示 true 手机端显示

# 动态彩带（会飘动的动态彩带）
canvas_fluttering_ribbon:
  enable: true
  mobile: false # false 手机端不显示 true 手机端显示

# canvas-nest
canvas_nest:
  enable: true
  color: '0,0,255' #color of lines, default: '0,0,0'; RGB values: (R,G,B).(note: use ',' to separate.)
  opacity: 0.7 # the opacity of line (0~1), default: 0.5.
  zIndex: -1 # z-index property of the background, default: -1.
  count: 99 # the number of lines, default: 99.
  mobile: false # false 手机端不显示 true 手机端显示

鼠标点击效果

烟花效果

# Mouse click effects: fireworks (鼠標點擊效果: 煙火特效)
fireworks:
  enable: false
  zIndex: 9999 # -1 or 9999
  mobile: false

爱心效果

# 点击出现爱心
click_heart:
  enable: true
  mobile: false

文字效果

# 点击出现文字，文字可自行修改
ClickShowText:
  enable: false
  text:
    - 富强
    - 民主
    - 文明
  fontSize: 15px
  random: false # 文字随机显示
  mobile: false

页面美化

调整ol、ul、h1-h5的样式（对应列表、标题的样式）

# field配置生效的区域:post-文章页生效、site-全站生效

# 1.修改主题配置文件
# 美化页面显示
beautify:
  enable: true
  field: site # site/post
  title-prefix-icon: '\f0c1' # title-prefix-icon填写的是fontawesome的icon的Unicode值
  title-prefix-icon-color: "#F47466"
  
# fontawesome参考地址：https://fontawesome.com/v5/cheatsheet

美化效果展示如下

自定义字体和字体大小

<1>全局字体

# Global font settings
# Don't modify the following settings unless you know how they work (非必要不要修改)
font:
  global-font-size:
  code-font-size:
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Lato, Roboto, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif
  code-font-family: consolas, Menlo, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif

<2>Blog标题字体

如果不需要配置则留空即可

# Font settings for the site title and site subtitle
# 左上角网站名字 主页居中网站名字
blog_title_font:
  font_link: https://fonts.googleapis.com/css?family=Titillium+Web&display=swap
  font-family: Titillium Web, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft JhengHei', 'Microsoft YaHei', sans-serif

网站副标题

# 主页subtitle
subtitle:
  enable: false
  # Typewriter Effect (打字效果)
  effect: true
  # loop (循环打字)
  loop: true
  # source 调用第三方服务
  # source: false 关闭调用
  # source: 1  调用一言网的一句话（简体） https://hitokoto.cn/
  # source: 2  调用一句网（简体） http://yijuzhan.com/
  # source: 3  调用今日诗词（简体） https://www.jinrishici.com/
  # subtitle 会先显示 source , 再显示 sub 的内容
  source: false
  # 如果关闭打字效果，subtitle 只会显示 sub 的第一行文字
  sub:
    - 今日事&#44;今日毕
    - Never put off till tomorrow what you can do today

hr水平分割线调整

hr_icon:
  enable: true
  icon: '\f197' # the unicode value of Font Awesome icon, such as '\3423'
  icon-top: # -20px:图标位于分割线上方;-10px:图标位于分割线中间;-0px:图标位于分割线下方

主页top_img显示大小

适用于版本号>=V1.2.0

默认显示全屏，site-info的区域会居中显示

# 主页设置
# 默认top_img全屏，site_info在中间
# 使用默认, 都无需填写（建议默认），2个都不填的话，会使用默认值
index_site_info_top: # 主页标题距离顶部距离  例如 300px/300em/300rem/10%
index_top_img_height:  #主页top_img高度 例如 300px/300em/300rem  不能使用百分比

页面加载动画preloader

# 加载动画 Loading Animation
preloader: true

图片大图查看模式

图片大图查看模式只能开启一个

# 禁止某张图片的大图查看模式可使用html格式引用图片，并为图片添加no-lightbox class名

# 方式1: fancybox http://fancyapps.com/fancybox/3/
fancybox: true

# 方式2: medium_zoom https://github.com/francoischalifour/medium-zoom
medium_zoom: true

图片懒加载

<1>新增hexo-lazyload-image模块

npm install hexo-lazyload-image --save

<2>修改主题配置文件

lazyload:
  enable: false
  field: site # site/post
  placeholder:
  blur: false

Snackbar弹窗

# Snackbar 弹窗
# https://github.com/polonel/SnackBar
# position 弹窗位置
# 可选 top-left / top-center / top-right / bottom-left / bottom-center / bottom-right
snackbar:
  enable: true
  position: bottom-left
  bg_light: '#49b1f5' #light mode时弹窗背景
  bg_dark: '#2d3035' #dark mode时弹窗背景

2.其他配置

扩展配置

CSS前缀

有些 CSS 并不是所有浏览器都支持，需要增加对应的前缀才会生效。

开启 css_prefix 后，会自动为一些 CSS 增加前缀。（会增加 20%的体积）

# Add the vendor prefixes to ensure compatibility
css_prefix: true

Open Graph

在 head 里增加一些 meta 资料，例如缩略图、标题、时间等等。当你分享网页到一些平臺时，平臺会读取 Open Graph 的内容，展示缩略图，标题等等信息。

# Open graph meta tags
# https://developers.facebook.com/docs/sharing/webmasters/
Open_Graph_meta: true

Instantpage

当鼠标悬停到链接上超过 65 毫秒时，Instantpage 会对该链接进行预加载，可以提升访问速度。

# https://instant.page/
# prefetch (预加载)
instantpage: true

Pangu

自动替你在网页中所有的中文字和半形的英文、数字、符号之间插入空白

# https://github.com/vinta/pangu.js
# Insert a space between Chinese character and English character (中英文之间添加空格)
pangu:
  enable: false
  field: post # site/post

Pjax

当用户点击链接，通过ajax更新页面需要变化的部分，然后使用HTML5的pushState修改浏览器的URL地址。这样可以不用重复加载相同的资源（css/js），从而提升网页的加载速度。

# Pjax [Beta]
# It may contain bugs and unstable, give feedback when you find the bugs.
# https://github.com/MoOx/pjax
pjax: 
  enable: true
  exclude:
    - /music/
    - /no-pjax/

目前pjax在butterfly的应用还不够稳定，具体参考butterfly和pjax文档内容https://github.com/MoOx/pjax

Injext

V2.3.0以上支持

# 如想添加额外的js/css/meta等等东西，可以在Inject里添加，支持添加到head(</body>标籤之前)和bottom(</html>标籤之前)。
inject:
  head:
  	- <link rel="stylesheet" href="/self.css">
  bottom:
  	- <script src="xxxx"></script>
 # 如果网站根目录不是'/',使用本地资源时，需加上你的根目录信息