本文主要分享：除了 markdown 的基本语法之外，文章可以使用的组件。在 Butterfly 官方中称为 标签外挂（Tag Plugins）。这些组件能够使得 hexo 文章内容的呈现方式更加丰富多彩。

Tabs 组件

使用方法

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

注意：

  • 其中的 <!-- --> 注释内容也是 Tabs 组件的一部分，并不是 markdown 中的注释**
  • 其中 [xxx] 仅用于描述可以替换的元素，替换后并没有方括号 []

Tabs 配置说明：

  • [tabs Unique name] - 必须
    • 针对当前页面，此 Tabs 的唯一标识字符串
    • 如果名称中存在空格，则生成的时候会替换为破折号 -
  • [index]
    • 指定选择 Tabs 里面的哪个 Tab 选项卡
    • 默认为第一个选项卡
    • 如果为 -1，则不会选择任何一个选项卡

Tab 配置说明

  • [Tab caption] 选项卡标题
    • 当前选项卡的标题
    • 如果没有标题，则会自动按照索引创建一个唯一标题
    • 如果没有标题且指定了图标，则标题为空
  • [@icon] 图标名称
    • FontAwesome 图标名称（全名，例如 fas fa-font）
    • 指定选项卡的图标，可以为空

模板效果

无指定选项卡

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

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

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

This is Tab 1.

This is Tab 2.

This is Tab 3.

带图标的选项卡

1
2
3
4
5
6
7
8
9
10
11
12
13
{% tabs test2 %}
<!-- tab 第一个 Tab -->
**tab名字为第一个Tab**
<!-- endtab -->

<!-- tab @fas fa-wind -->
**只有图标 没有Tab名字**
<!-- endtab -->

<!-- tab 风 @fas fa-wind -->
**名字+icon**
<!-- endtab -->
{% endtabs %}

tab名字为第一个Tab

只有图标 没有Tab名字

名字+icon

Note 引导标注 (Bootstrap Callout)

修改配置文件

修改 主题配置文件，可以设置默认的显示风格及默认是否启用 icon

1
2
3
4
5
6
7
8
9
10
11
12
13
# Note (Bootstrap Callout)
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: flat # 默认使用的类型：simple, modern, flat. 设置为 disabled 则禁用。
  icons: true # 默认是否启用 icon 图标
  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

Note 类型

内置标识

注意：

  • 其中 [xxx] 仅用于描述可以替换的元素，替换后并没有方括号 []

内置标识：不能自定义 icon，有常用的若干个类型选择：

  • [class] 表示当前类型
    • 空, default, primary, success, info, warning, danger
  • [no-icon]：是否显示 icon，可以替代配置中默认设置 icon
    • true, false
  • [style] 显示的风格，可以替代配置中默认设置 style
    • simple, modern, flat
1
2
3
{% note [class] [no-icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{% note simple %}
默认 提示块标签
{% endnote %}

{% note default simple %}
default 提示块标签
{% endnote %}

{% note primary simple %}
primary 提示块标签
{% endnote %}

{% note success simple %}
success 提示块标签
{% endnote %}

{% note info simple %}
info 提示块标签
{% endnote %}

{% note warning simple %}
warning 提示块标签
{% endnote %}

{% note danger simple %}
danger 提示块标签
{% endnote %}

默认 提示块标签

default 提示块标签

primary 提示块标签

success 提示块标签

info 提示块标签

warning 提示块标签

danger 提示块标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{% note modern %}
默认 提示块标签
{% endnote %}

{% note default modern %}
default 提示块标签
{% endnote %}

{% note primary modern %}
primary 提示块标签
{% endnote %}

{% note success modern %}
success 提示块标签
{% endnote %}

{% note info modern %}
info 提示块标签
{% endnote %}

{% note warning modern %}
warning 提示块标签
{% endnote %}

{% note danger modern %}
danger 提示块标签
{% endnote %}

默认 提示块标签

default 提示块标签

primary 提示块标签

success 提示块标签

info 提示块标签

warning 提示块标签

danger 提示块标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{% note flat %}
默认 提示块标签
{% endnote %}

{% note default flat %}
default 提示块标签
{% endnote %}

{% note primary flat %}
primary 提示块标签
{% endnote %}

{% note success flat %}
success 提示块标签
{% endnote %}

{% note info flat %}
info 提示块标签
{% endnote %}

{% note warning flat %}
warning 提示块标签
{% endnote %}

{% note danger flat %}
danger 提示块标签
{% endnote %}

默认 提示块标签

default 提示块标签

primary 提示块标签

success 提示块标签

info 提示块标签

warning 提示块标签

danger 提示块标签

自定义 icon 标识

Butterfly 3.2.0 以上版本支持

自定义 icon 支持使用 fontawesome 图标定义标签前面的图标：

  • [color]: Note 标签显示的颜色
    • default / blue / pink / red / purple / orange / green
  • [icon]: 可配置自定义 icon (也可以配置 no-icon )
    • 只支持 fontawesome 图标
  • [style]: 风格
    • simple, modern, flat
1
2
3
{% note [color] [icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' simple %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' simple %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' simple %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' simple%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' simple %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' simple %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' simple %}
前端最讨厌的浏览器
{% endnote %}

你是刷 Visa 还是 UnionPay

2021年快到了….

小心开车 安全至上

这是三片呢？还是四片？

你是刷 Visa 还是 UnionPay

剪刀石头布

前端最讨厌的浏览器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' modern %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' modern %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' modern %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' modern%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' modern %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' modern %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' modern %}
前端最讨厌的浏览器
{% endnote %}

你是刷 Visa 还是 UnionPay

2021年快到了….

小心开车 安全至上

这是三片呢？还是四片？

你是刷 Visa 还是 UnionPay

剪刀石头布

前端最讨厌的浏览器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% note 'fab fa-cc-visa' flat %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note blue 'fas fa-bullhorn' flat %}
2021年快到了....
{% endnote %}
{% note pink 'fas fa-car-crash' flat %}
小心开车 安全至上
{% endnote %}
{% note red 'fas fa-fan' flat%}
这是三片呢？还是四片？
{% endnote %}
{% note orange 'fas fa-battery-half' flat %}
你是刷 Visa 还是 UnionPay
{% endnote %}
{% note purple 'far fa-hand-scissors' flat %}
剪刀石头布
{% endnote %}
{% note green 'fab fa-internet-explorer' flat %}
前端最讨厌的浏览器
{% endnote %}

你是刷 Visa 还是 UnionPay

2021年快到了….

小心开车 安全至上

这是三片呢？还是四片？

你是刷 Visa 还是 UnionPay

剪刀石头布

前端最讨厌的浏览器

Gallery 相册

Butterfly 2.0.0 以上支持。用于展示一组图片的组件。

本地导入指的是：所有图片的 URL 由 markdown 中直接定义展示。

  • [layload]: 一次展示部分图片，点击按钮加载更多图片
    • true, false。默认为 false
  • [rowHeight]: 图片显示的高度
    • 如果需要一行显示更多的图片，可设置更小的数字。默认为 220。
  • [limit]: 每次加载照片的数量
    • 默认为 10。
1
2
3
{% gallery [lazyload],[rowHeight],[limit] %}
markdown 图片格式
{% endgallery %}

举例：

1
2
3
4
5
{% gallery %}
![](https://cdn.catsky.org/catskyCDN/img/blog/hexo/galleryAlbum/blog_galleryAlbum_display_photo_1.webp)
![](https://cdn.catsky.org/catskyCDN/img/blog/hexo/galleryAlbum/blog_galleryAlbum_display_photo_2.webp)
![](https://cdn.catsky.org/catskyCDN/img/blog/hexo/galleryAlbum/blog_galleryAlbum_display_photo_3.webp)
{% endgallery %}



远程拉取指的是：从远程获取相册所有图片的 URL，用 json 描述所有图片的 URL。用 gallery url 表示当前的图库是远程拉取模式。

  • [link]: 获取 json 的 URL
  • [layload]: 一次展示部分图片，点击按钮加载更多图片
    • true, false。默认为 false
  • [rowHeight]: 图片显示的高度
    • 如果需要一行显示更多的图片，可设置更小的数字。默认为 220。
  • [limit]: 每次加载照片的数量
    • 默认为 10。
1
2
{% gallery url,[link],[lazyload],[rowHeight],[limit] %}
{% endgallery %}

Gallery 相册图库

Butterfly 2.2.0 以上支持。用于展示一组图片，利用图库页面的方式进行展示，图库组件为图库页面的入口。即创建一组图片的图库入口组件，点击图库入口组件后进入对应图库页面进行查看。一般搭配 Gallery 相册 共同使用

  • [name]: 图库名字
  • [description]：图库描述
  • [link]：连接到对应相册的地址
    • 一般是一个 Page 页面，使用以 /source 为根目录的相对路径表示：例如 /Gallery/galleryAlbumDisplayPhoto
  • [img-url]：图库封面的地址
1
2
3
4
5
<div class="gallery-group-main">
{% galleryGroup [name] [description] [link] [img-url] %}
{% galleryGroup [name] [description] [link] [img-url] %}
{% galleryGroup [name] [description] [link] [img-url] %}
</div>

举例说明：

1
2
3
<div class="gallery-group-main">
{% galleryGroup '图库展示' '图库图片展示' '/Gallery/galleryAlbumDisplayPhoto' https://cdn.catsky.org/catskyCDN/img/blog/hexo/galleryAlbum/blog_galleryAlbum_display_photo_2.webp %}
</div>
Group Image Gallery
图库展示

图库图片展示

tag-hide 隐藏内容

Butterfly 2.2.0 以上支持。不建议将标题设置为隐藏，会导致目录出现问题。

inline 在文本里面添加按钮隐藏内容，只限文字

  • [content]: 【必须】文本内容
  • [display]: 按钮显示的文字
  • [bg]: 按钮的背景颜色
  • [color]: 按钮文字的颜色
1
{% hideInline [content],[display],[bg],[color] %}

举例:

1
2
3
测试问题? {% hideInline 测试答案,查看答案,#FF7242,#fff %}

测试问题? {% hideInline 测试答案 %}

测试问题? 测试答案

测试问题? 测试答案

block: 独立的隐藏内容，隐藏更多内容，包括图片，代码块等等

  • [content]: 【必须】文本内容
  • [display]: 按钮显示的文字
  • [bg]: 按钮的背景颜色
  • [color]: 按钮文字的颜色
1
2
3
{% hideBlock [display],[bg],[color] %}
[content]
{% endhideBlock %}

举例：

1
2
3
4
测试问题
{% hideBlock 查看答案 %}
测试答案
{% endhideBlock %}

测试问题

测试答案

Butterfly 2.3.0 以上支持

需要展示的内容太多，可以把它 隐藏在收缩框 里，需要时再把它展开。

  • [content]: 【必须】文本内容
  • [display]: 按钮显示的文字
  • [bg]: 按钮的背景颜色
  • [color]: 按钮文字的颜色
  • 注意事项
    • display 不能包含英文逗号，可用 &sbquo;
1
2
3
{% hideToggle [display],[bg],[color] %}
[content]
{% endhideToggle %}

举例：

1
2
3
4
5
6
7
8
9
10
{% hideToggle Butterfly安装方法 %}
在你的博客根目录里

git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

如果想要安装比较新的dev分支，可以

git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

{% endhideToggle %}
Butterfly安装方法

在你的博客根目录里

git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

如果想要安装比较新的dev分支，可以

git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

Button 按钮

Butterfly 3.0 以上支持

Button 组件使用

  • [url]: 【必须】链接
  • [text]: 【必须】按钮文字
  • [icon]: 图标
  • [color]:
    • 按钮背景顔色（默认 style 时）
    • 按钮字体和边框颜色（outline 时）
    • default/blue/pink/red/purple/orange/green
  • [style]: 按钮样式 默认实心
    • outline/留空
  • [layout]: 按钮布局 默认为 line
    • block/留空line
  • [position]: 按钮位置 前提是设置了 layout 为 block 默认为左边
    • center/right/留空left
  • [size]: 按钮大小
    • larger/留空
1
{% btn [url],[text],[icon],[color] [style] [layout] [position] [size] %}

举例：

1
2
3
4
5
Butterfly 主题，点击：{% btn 'https://butterfly.js.org/',Butterfly %}
Butterfly 主题，点击：{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right %}
Butterfly 主题，点击：{% btn 'https://butterfly.js.org/',Butterfly,,outline %}
Butterfly 主题，点击：{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline %}
Butterfly 主题，点击：{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,larger %}

Butterfly 主题，点击：Butterfly
Butterfly 主题，点击：Butterfly
Butterfly 主题，点击：Butterfly
Butterfly 主题，点击：Butterfly
Butterfly 主题，点击：Butterfly

1
2
3
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block center larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block right outline larger %}
Butterfly Butterfly Butterfly

通过 div 设置 button 的位置

1
2
3
4
5
6
7
8
9
<div class="btn-center">
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline blue larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline pink larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline red larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline purple larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline orange larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline green larger %}
</div>
Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly

mermaid 绘图

使用 mermaid 组件可以绘制 Flowchart（流程图）、Sequence diagram（时序图）、Class Diagram（类别图）、State Diagram（状态图）、Gantt（甘特图）和 Pie Chart（圆形图），具体可以查看 mermaid 文档

修改配置文件开启组件

1
2
3
4
5
6
7
8
# mermaid
# see https://github.com/mermaid-js/mermaid
mermaid:
  enable: true # 开启 mermaid 组件
  # built-in themes: default/forest/dark/neutral
  theme:
    light: default
    dark: dark

具体使用见文档，格式如下：

1
2
3
{% mermaid %}
内容
{% endmermaid %}

inlineImg 内联元素

主题中的图片都是默认以块级元素显示，如果你想以内联元素显示，可以使用这个标签外挂。

  • [src]:【必须】图片链接
  • [height]: 图片高度限制
1
{% inlineImg [src] [height] %}

举例：

1
这是一张风景图片：{% inlineImg https://cdn.catsky.org/catskyCDN/img/blog/hexo/galleryAlbum/blog_galleryAlbum_display_photo_3.webp 150px %}

这是一张风景图片：

label 高亮文字

由于 hexo 的渲染限制， 在段落开头使用 label 标签外挂会出现一些问题。例如：连续开头使用 label 标签外挂的段落无法换行

高亮对应的文件：

  • [text]: 文字
  • [color]: 背景颜色，默认为 default
    • default/blue/pink/red/purple/orange/green
1
{% label [text] [color] %}

举例：

1
{% label label %} 用于高亮 {% label 文字 orange %} 。

timeline 时间线

Butterfly 4.0.0 以上支持。用于创建一条时间线。

    • default(留空) / blue / pink / red / purple / orange / green
1
2
3
4
5
6
7
8
{% timeline [title],[color] %}
<!-- timeline [title] -->
xxxxx
<!-- endtimeline -->
<!-- timeline [title] -->
xxxxx
<!-- endtimeline -->
{% endtimeline %}

举例：

默认颜色：

1
2
3
4
5
{% timeline 2023 %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2023

01-02

这是测试页面

修改颜色：

1
2
3
4
5
{% timeline 2023,pink %}
<!-- timeline 01-02 -->
这是测试页面
<!-- endtimeline -->
{% endtimeline %}

2023

01-02

这是测试页面

flink 友链组件

Butterfly 4.1.0 支持。用于在任何 markdown 中插入类似友情链接列表效果

内容和友链页面一致：

1
2
3
4
5
6
7
8
9
{% flink %}
- class_name: # 友链组标题
  class_desc: # 友链组描述
  link_list:
    - name:     # 友链名称
      link:     # 友链链接
      avatar:   # 友链头像
      descr:    # 描述
{% endflink %}

举例:

1
2
3
4
5
6
7
8
9
{% flink %}
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: catsky
      link: https://catsky.org/
      avatar: https://cdn.catsky.org/catskyCDN/img/blog/catsky/blog_samll-toy-windmill.webp
      descr: Cat's Blog
{% endflink %}

abcjs 乐谱展示

修改配置文件开启

修改 主题配置文件：

1
2
3
4
5
6
# abcjs (乐谱渲染)
# See https://github.com/paulrosen/abcjs
# ---------------
abcjs:
  enable: true    # 开启
  per_page: true  # 是否在每个页面均开启

组件使用方法

1
2
3
{% score %}
乐谱代码
{% endscore %}

series 系列文章

在页面上显示系列文章

修改配置文件

1
2
3
4
5
series:
   enable: true
   orderBy: 'title' # 按照 title 或者 data 排序
   order: 1 # 排序方式 -> 1: asc for ascending; -1: desc for descending
   number: true

组件使用方法

  • 使用：在文章的 front-matter 上添加参数 series，作为当前 文章的标识
  • 效果：使用此标签外挂，会把 相同标识的文章以列表的形式展示
1
2
{% series %}
{% series [series name] %}