主题标签插件完整指南

主题提供了丰富的标签插件（Tag Plugins），让你可以在 Markdown 文章中轻松插入各种样式丰富的组件。本文档将详细介绍所有可用的标签插件及其使用方法。

📋 目录

1. 按钮插件 (btn)

语法

{% btn url, text, icon, option %}

参数说明

  • url: 按钮链接地址（必填）
  • text: 按钮显示文本（可选）
  • icon: Font Awesome 图标类名（可选）
  • option: 样式选项（可选）
    • color: 颜色样式 - default/blue/pink/red/purple/orange/green
    • outline: 轮廓样式
    • center: 居中对齐
    • block: 块级按钮
    • larger: 大尺寸按钮

使用示例

<!-- 基础按钮 -->
{% btn https://github.com, GitHub %}

<!-- 带图标和颜色 -->
{% btn https://github.com, GitHub, fab fa-github, blue %}

<!-- 轮廓样式按钮 -->
{% btn https://butterfly.js.org, 访问官网, fas fa-home, pink outline %}

<!-- 块级大按钮 -->
{% btn https://butterfly.js.org, 访问Butterfly主题官网, fas fa-home, green block larger %}

<!-- 居中对齐 -->
{% btn https://github.com, 查看源码, fab fa-github, purple center %}

渲染效果

GitHub

2. 提示框插件 (note/subnote)

语法

{% note [style] [icon] [color] %}
内容支持 Markdown 语法
{% endnote %}

参数说明

  • style: 样式类型（可选）
    • default: 默认样式
    • primary: 主要样式
    • success: 成功样式
    • info: 信息样式
    • warning: 警告样式
    • danger: 危险样式
  • icon: Font Awesome 图标类名（可选）
  • color: 颜色样式（可选）

使用示例

<!-- 默认提示框 -->
{% note %}
这是默认提示框，用于一般信息展示。
{% endnote %}

<!-- 成功提示框 -->
{% note success %}
操作成功完成！
{% endnote %}

<!-- 信息提示框 -->
{% note info %}
这是一条重要信息，请注意查看。
{% endnote %}

<!-- 警告提示框 -->
{% note warning %}
警告：此操作不可逆，请谨慎操作。
{% endnote %}

<!-- 危险提示框 -->
{% note danger %}
危险：删除操作将永久删除数据，无法恢复。
{% endnote %}

<!-- 带自定义图标 -->
{% note info fas fa-lightbulb %}
这是一个带自定义图标的提示框。
{% endnote %}

<!-- 主要样式 -->
{% note primary %}
这是主要信息的提示框。
{% endnote %}

渲染效果

这是默认提示框，用于一般信息展示。

操作成功完成！

3. 标签页插件 (tabs)

语法

{% tabs [name], [active] %}
<!-- tab [title]@[icon] -->
内容支持 Markdown 语法
<!-- endtab -->
{% endtabs %}

参数说明

  • name: 标签页组名称（可选，默认为 “tab”）
  • active: 默认激活的标签页序号（可选，默认为 1）
  • title: 标签页标题
  • icon: Font Awesome 图标类名（可选）

使用示例

{% tabs 代码示例, 1 %}
<!-- tab JavaScript@fab fa-js -->
```javascript
console.log('Hello, World!');
print("Hello, World!")
System.out.println("Hello, World!");
{% endtabs %} 
{% endraw %}

### 嵌套标签页

Butterfly 支持嵌套标签页，可以使用 `subtabs` 和 `subsubtabs`：

{% raw %}
```markdown
{% tabs 前端技术栈 %}
<!-- tab HTML@fab fa-html5 -->
HTML 基础内容
<!-- endtab -->

<!-- tab CSS@fab fa-css3-alt -->
CSS 样式内容
<!-- endtab -->

<!-- tab JavaScript@fab fa-js -->
JavaScript 相关内容

{% subtabs JavaScript框架 %}
<!-- tab Vue@fab fa-vuejs -->
Vue.js 框架介绍
<!-- endtab -->

<!-- tab React@fab fa-react -->
React 框架介绍
<!-- endtab -->
{% endsubtabs %}

<!-- endtab -->
{% endtabs %}

4. 隐藏内容插件 (hide)

Butterfly 提供了三种隐藏内容的方式：

4.1 hideInline - 行内隐藏

语法

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

参数说明

  • content: 要隐藏的内容（必填，不能包含单引号，可用 &apos; 代替）
  • display: 按钮显示文本（可选，默认为 “Click”）
  • bg: 按钮背景色（可选）
  • color: 按钮文字颜色（可选）

使用示例

{% hideInline 这是隐藏的内容, 点击查看答案, #f0f0f0, #333 %}

4.2 hideBlock - 块级隐藏

语法

{% hideBlock display, bg, color %}
内容支持 Markdown 语法
{% endhideBlock %}

使用示例

{% hideBlock 点击查看答案 %}
这是一段被隐藏的内容，支持 Markdown 语法。

- 列表项 1
- 列表项 2
- 列表项 3
{% endhideBlock %}

4.3 hideToggle - 折叠隐藏

语法

{% hideToggle display, bg, color %}
内容支持 Markdown 语法
{% endhideToggle %}

使用示例

{% hideToggle 点击展开详细内容 %}
这是折叠的内容，点击后可以展开查看。

支持多段内容：

1. 第一项
2. 第二项
3. 第三项

也可以包含代码：

```python
def hello():
    print("Hello!")
{% endhideToggle %} 
{% endraw %}

---

## 5. 标签插件 (label)

### 语法

{% raw %}
```markdown
{% label text color %}

参数说明

  • text: 标签文本（必填）
  • color: 标签颜色（可选，默认为 default）
    • default: 默认
    • primary: 主要
    • success: 成功
    • info: 信息
    • warning: 警告
    • danger: 危险
    • pink: 粉色
    • red: 红色
    • orange: 橙色
    • green: 绿色
    • blue: 蓝色
    • purple: 紫色

使用示例

{% label 重要 %}
{% label 已完成 success %}
{% label 待处理 warning %}
{% label 错误 danger %}
{% label 新功能 primary %}
{% label 热门 pink %}
{% label 推荐 blue %}

渲染效果

重要 已完成 待处理 错误

6. 时间线插件 (timeline)

语法

{% timeline [headline], [color] %}
<!-- timeline [title] -->
内容支持 Markdown 语法
<!-- endtimeline -->
{% endtimeline %}

参数说明

  • headline: 时间线标题（可选）
  • color: 时间线颜色（可选）
  • title: 时间节点标题

使用示例

{% timeline 项目开发时间线 %}
<!-- timeline 2023-01-15 -->
项目启动，完成需求分析。
<!-- endtimeline -->

<!-- timeline 2023-02-20 -->
完成数据库设计，开始后端开发。
<!-- endtimeline -->

<!-- timeline 2023-03-10 -->
后端 API 开发完成，开始前端开发。
<!-- endtimeline -->

<!-- timeline 2023-04-01 -->
前端开发完成，进入测试阶段。
<!-- endtimeline -->

<!-- timeline 2023-04-15 -->
项目上线发布。
<!-- endtimeline -->
{% endtimeline %}

语法

{% gallery [button], [limit], [firstLimit] %}
![图片描述](图片URL)
![图片描述](图片URL)
{% endgallery %}

或者使用 URL 方式：

{% gallery url, [url], [button] %}

参数说明

  • button: 是否显示加载更多按钮（可选，默认为 false）
  • limit: 每页显示数量（可选，默认为 10）
  • firstLimit: 首次加载数量（可选，默认为 10）
  • url: 图片 URL 地址（URL 模式）

使用示例

{% gallery true, 6, 6 %}
![图片1](https://example.com/image1.jpg)
![图片2](https://example.com/image2.jpg)
![图片3](https://example.com/image3.jpg)
![图片4](https://example.com/image4.jpg)
![图片5](https://example.com/image5.jpg)
![图片6](https://example.com/image6.jpg)
{% endgallery %}

7.2 galleryGroup - 相册组

语法

{% galleryGroup [name] [descr] [url] [img] %}

参数说明

  • name: 相册组名称
  • descr: 相册组描述
  • url: 相册链接地址
  • img: 相册封面图片

使用示例

{% galleryGroup 旅行照片 记录美好时光 /photos/travel /images/travel-cover.jpg %}
{% galleryGroup 美食分享 分享美食体验 /photos/food /images/food-cover.jpg %}

8. 行内图片插件 (inlineImg)

语法

{% inlineImg [img] [height] %}

参数说明

  • img: 图片路径或 URL（必填）
  • height: 图片高度（可选，单位：px）

使用示例

这是一段文字，{% inlineImg /images/logo.png 30px %} 这里插入了一个行内图片。

{% inlineImg https://example.com/icon.png 40px %} 这是另一个行内图片。

9. 系列文章插件 (series)

前置配置

首先需要在主题配置文件中启用系列插件：

series:
  enable: true
  orderBy: 'title'  # 或 'date'
  order: 1  # 1: 升序, -1: 降序
  number: true  # 是否显示序号

语法

在文章 Front Matter 中添加 series 字段：

---
title: 文章标题
series: 系列名称
---

在文章中使用标签插件：

{% series [series name] %}

参数说明

  • series name: 系列名称（可选，如果不指定则使用当前文章的 series 字段值）

使用示例

文章1 (series.md):

---
title: Python基础教程（一）
series: Python教程
---

文章2 (series-2.md):

---
title: Python基础教程（二）
series: Python教程
---

在文章中使用：

{% series Python教程 %}

或者：

{% series %}

10. 乐谱插件 (score)

前置配置

需要在主题配置文件中启用 ABCJS：

abcjs:
  enable: true
  per_page: true

语法

{% score %}
[参数JSON]
------
ABC乐谱代码
{% endscore %}

使用示例

{% score %}
{}
------
X:1
T:示例乐谱
M:4/4
L:1/4
K:C
C D E F|G A B c|
{% endscore %}

11. 图表插件 (chartjs)

前置配置

需要在主题配置文件中启用 ChartJS：

chartjs:
  enable: true

语法

{% chartjs [width], [abreast], [chartId] %}
<!-- chart -->
图表配置 JSON
<!-- endchart -->
<!-- desc -->
图表描述（可选）
<!-- enddesc -->
{% endchartjs %}

参数说明

  • width: 图表宽度百分比（可选）
  • abreast: 是否并排显示（可选，布尔值）
  • chartId: 图表 ID（可选）

使用示例

{% chartjs 100% %}
<!-- chart -->
{
  "type": "bar",
  "data": {
    "labels": ["一月", "二月", "三月", "四月"],
    "datasets": [{
      "label": "销售额",
      "data": [12, 19, 3, 5],
      "backgroundColor": [
        "rgba(255, 99, 132, 0.2)",
        "rgba(54, 162, 235, 0.2)",
        "rgba(255, 206, 86, 0.2)",
        "rgba(75, 192, 192, 0.2)"
      ]
    }]
  },
  "options": {
    "scales": {
      "y": {
        "beginAtZero": true
      }
    }
  }
}
<!-- endchart -->
<!-- desc -->
2023年第一季度销售额统计
<!-- enddesc -->
{% endchartjs %}

12. 流程图插件 (mermaid)

前置配置

需要在主题配置文件中启用 Mermaid：

mermaid:
  enable: true
  code_write: false
  theme:
    light: default
    dark: dark

语法

方式一：使用标签插件

{% mermaid %}
流程图代码
{% endmermaid %}

方式二：使用代码块（当 code_write: false 时）

```mermaid
流程图代码
```

使用示例

{% mermaid %}
graph TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作1]
    B -->|否| D[执行操作2]
    C --> E[结束]
    D --> E
{% endmermaid %}

或者使用代码块：

```mermaid
sequenceDiagram
    participant A as 用户
    participant B as 服务器
    A->>B: 发送请求
    B-->>A: 返回响应
```

支持的图表类型

  • 流程图（Flowchart）
  • 序列图（Sequence Diagram）
  • 甘特图（Gantt Chart）
  • 类图（Class Diagram）
  • 状态图（State Diagram）
  • 实体关系图（ER Diagram）
  • 用户旅程图（User Journey）
  • 等等…

语法

{% flink %}
- class_name: 分类名称
  class_desc: 分类描述
  link_list:
    - name: 链接名称
      link: 链接地址
      avatar: 头像地址
      descr: 链接描述
{% endflink %}

使用示例

{% flink %}
- class_name: 技术博客
  class_desc: 优秀的技术博客推荐
  link_list:
    - name: Butterfly 主题
      link: https://butterfly.js.org
      avatar: https://butterfly.js.org/img/favicon.png
      descr: 一个简洁美观的 Hexo 主题
    - name: Hexo 官方
      link: https://hexo.io
      avatar: https://hexo.io/favicon.ico
      descr: 快速、简洁且高效的博客框架

- class_name: 工具网站
  class_desc: 实用的在线工具
  link_list:
    - name: GitHub
      link: https://github.com
      avatar: https://github.com/favicon.ico
      descr: 全球最大的代码托管平台
{% endflink %}

🎨 组合使用示例

标签插件可以灵活组合使用，创造出更丰富的效果：

{% note info %}
这是一个提示框，里面可以包含其他标签插件。
{% endnote %}

{% tabs 组合示例 %}
<!-- tab 按钮组 -->
{% btn https://github.com, GitHub, fab fa-github, blue %}
{% btn https://butterfly.js.org, 官网, fas fa-home, pink %}
<!-- endtab -->

<!-- tab 标签组 -->
{% label 重要 %}
{% label 已完成 success %}
{% label 待处理 warning %}
<!-- endtab -->
{% endtabs %}

📝 注意事项

  1. 标签插件语法：所有标签插件使用 {% %} 包裹，区分大小写
  2. Markdown 支持：大部分标签插件内部支持 Markdown 语法
  3. 参数分隔：多个参数使用逗号 , 分隔
  4. 嵌套使用：部分标签插件支持嵌套使用（如 tabs、note）
  5. 配置要求：部分插件（如 mermaid、chartjs、score）需要先在主题配置中启用
  6. 图标使用：图标使用 Font Awesome 类名，需要在主题中引入 Font Awesome

🔗 相关资源

📚 总结

Butterfly 主题提供了 13 种标签插件，涵盖了按钮、提示框、标签页、隐藏内容、标签、时间线、相册、图片、系列文章、乐谱、图表、流程图和友情链接等功能。这些标签插件可以大大增强文章的视觉效果和交互性，让你的博客内容更加丰富多彩。

希望本文档能帮助你更好地使用 Butterfly 主题的标签插件功能。如有疑问，欢迎参考官方文档或提出 issue。

最后更新: 2023-09-07