外挂标签可以在 Markdown 中快速插入图表、画廊、视频、按钮等丰富内容。内置标签无需额外安装;插件标签需要先安装对应插件,再按照示例调用。
建议优先使用内置标签。只有在确实需要扩展能力时,再引入额外插件,以减少依赖和维护成本。
Butterfly 兼容说明
从 hexo-solitude-tag@1.1.0 开始,Solitude 已兼容 Butterfly 文档中的 14 组原生外挂标签。GalleryGroup、Gallery、Mermaid、Tabs 继续由主题提供,其余语法由插件提供,并统一使用 Solitude 的视觉样式。
| Butterfly 标签组 |
可用语法 |
提供方 |
| GalleryGroup |
galleryGroup |
Solitude 主题 |
| Gallery |
gallery |
Solitude 主题 |
| Tag-hide |
hideInline、hideBlock、hideToggle |
hexo-solitude-tag |
| Mermaid |
mermaid |
Solitude 主题 |
| Tabs |
tabs |
Solitude 主题 |
| Button |
btn,并保留 button |
hexo-solitude-tag |
| InlineImg |
inlineImg,并保留 inline_img |
hexo-solitude-tag |
| Label |
label |
hexo-solitude-tag |
| Timeline |
注释块写法,并保留 timeline + timenode |
hexo-solitude-tag |
| Note |
note、subnote |
hexo-solitude-tag |
| Flink |
flink |
hexo-solitude-tag |
| ABCJS |
score |
hexo-solitude-tag |
| Series |
series |
hexo-solitude-tag |
| Chart.js |
chartjs |
hexo-solitude-tag |
从 Butterfly 迁移时,大多数文章无需修改。旧版 Solitude 的 button、inline_img、timeline + timenode 语法仍然有效;Butterfly 的 btn、inlineImg、subnote 和注释块 Timeline 可以直接使用。
hexo-solitude-tag@2 面向 Hexo 8,需要 Node.js 20.19 或更高版本。它保留 1.x 的标签语法、配置项和输出类名,但把浏览器逻辑改为全站共用的可缓存资源,并在 PJAX 跳转时清理图表、复用仓库请求。仍在使用 Hexo 7 或旧版 Node.js 的站点应继续使用 hexo-solitude-tag@1。
2.0 正式发布前,本 Demo 的 Registry 依赖仍保持在可安装的 1.1.x;本文中的标签效果与 2.0 保持兼容。
内置标签
Chart
图表标签,用于显示图表。
打开配置文件中开关
1 2
| {% chart %} {% endchart %}
|
Gallery
图片列表标签,用于显示图片列表。
1 2
| {% gallery %} {% endgallery %}
|
1 2 3 4 5 6 7 8 9
| {% gallery %}
    
{% endgallery %}
|
GalleryGroup
图片组标签,用于显示图片组。
1
| {% galleryGroup 'name' 'desc' 'url' 'img' %}
|
| 参数 |
说明 |
默认值 |
| name |
图片组名称 |
无 |
| desc |
图片组描述 |
无 |
| url |
图片组链接 |
无 |
| img |
图片组预览图 |
无 |
1 2 3 4
| <div class='gallery-group-main'> {% galleryGroup '旅行' '出行拍摄的杂七杂八' 'https://solitude.js.org' 'https://s3.qjqq.cn/47/674c6e226855e.png!color' %} {% galleryGroup '旅行' '出行拍摄的杂七杂八' 'https://solitude.js.org' 'https://s3.qjqq.cn/47/674c6e5d63fda.png!color' %} </div>
|
旅行
出行拍摄的杂七杂八
旅行
出行拍摄的杂七杂八
Mermaid
Mermaid 标签,用于显示 Mermaid 图表。
1 2 3
| {% mermaid %} content {% endmermaid %}
|
1 2 3 4 5 6 7 8
| {% mermaid %} pie title Key elements in Product X "Calcium" : 42.96 "Potassium" : 50.05 "Magnesium" : 10.01 "Iron" : 5 {% endmermaid %}
|
Typeit
Typeit 标签,用于显示 Typeit 动画。
1 2 3
| {% typeit 'div' %} options {% endtypeit %}
|
1 2 3 4
| {% typeit 'div' } waitUntilVisible: true, strings: "Alex MacArthur", {% endtypeit %}
|
Tabs
标签页标签,用于显示标签页。
1 2 3 4 5 6 7 8 9
| {% tabs 唯一名称, [index] %}
<!-- tab [唯一Tab] [@icon] -->
任何内容(也支持内联标签)。
<!-- endtab -->
{% endtabs %}
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
| {% tabs test1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->
<!-- tab -->
**This is Tab 2.**
<!-- endtab -->
<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}
|
插件标签
安装插件
2.0 环境要求:Hexo 8、Node.js 20.19+。从 1.x 升级不需要改写文章或 solitude_tag 配置。
Butterfly 原生语法示例
以下示例均为实时效果。隐藏内容支持鼠标与键盘操作;Chart.js 和 ABCJS 仅在文章使用对应标签时按需加载。
Tag-hide
1 2 3 4 5 6 7 8 9 10
| {% hideInline 这是一段行内隐藏内容,点击查看 %}
{% hideBlock 查看块级内容 %} 块级内容支持 **Markdown**。 {% endhideBlock %}
{% hideToggle 展开更多内容 %} - Hide Toggle 同样支持 Markdown - 再次点击按钮可收起内容 {% endhideToggle %}
|
行内效果:这是一段行内隐藏内容
- Hide Toggle 同样支持 Markdown
- 再次点击按钮可收起内容
1 2 3
| {% btn https://solitude.js.org/zh,访问 Solitude,fas fa-link,blue %} 支持行内图片 {% inlineImg /img/post-covers/hexo-tag-plugins.webp 24px %} 当前状态:{% label 兼容完成 green %}
|
访问 Solitude
支持行内图片
,当前状态:兼容完成
Note 与 Timeline
subnote 是 note 的兼容别名;Note 默认样式可通过 solitude_tag.note.style 配置。
1 2 3 4 5 6 7 8
| {% timeline 兼容进度,blue %} <!-- timeline 1.1.0 发布 --> 完成 Butterfly 原生标签兼容。 <!-- endtimeline --> <!-- timeline Demo 接入 --> 演示文章使用 Registry 中的正式版本。 <!-- endtimeline --> {% endtimeline %}
|
Flink
Flink 内容使用 YAML;链接、文本和图片属性会按上下文安全处理。
1 2 3 4 5 6 7 8 9
| {% flink %} - class_name: 推荐站点 class_desc: Solitude 相关链接 link_list: - name: Solitude link: https://solitude.js.org/zh avatar: /img/post-covers/hexo-tag-plugins.webp descr: 一款简洁、优雅且易用的 Hexo 主题 {% endflink %}
|
ABCJS 乐谱
1 2 3 4 5 6 7 8 9 10
| {% score %} {"responsive":"resize"} ------ X:1 T:Solitude Scale M:4/4 L:1/4 K:C C D E F|G A B c| {% endscore %}
|
X:1
T:Solitude Scale
M:4/4
L:1/4
K:C
C D E F|G A B c|
Series
在文章 Front-matter 中设置相同的 series 值,即可生成系列目录。排序与编号可通过 solitude_tag.series 配置。
1
| series: Butterfly 原生外挂标签兼容
|
1
| {% series Butterfly 原生外挂标签兼容 %}
|
- Solitude 外挂标签使用指南
Chart.js
Chart.js 配置使用严格 JSON。渲染失败时会显示可读提示,同时不会中断整站构建。
1 2 3 4 5 6 7 8
| {% chartjs 100,false,butterfly-compat %} <!-- chart --> {"type":"bar","data":{"labels":["主题内置","插件提供"],"datasets":[{"label":"兼容标签组","data":[4,10],"backgroundColor":["#49b1f5","#425aef"]}]},"options":{"responsive":true,"plugins":{"legend":{"display":false}}}} <!-- endchart --> <!-- desc --> Butterfly 14 组标签的提供方分布。 <!-- enddesc --> {% endchartjs %}
|
{"type":"bar","data":{"labels":["主题内置","插件提供"],"datasets":[{"label":"兼容标签组","data":[4,10],"backgroundColor":["#49b1f5","#425aef"]}]},"options":{"responsive":true,"plugins":{"legend":{"display":false}}}}
Youtube
Youtube 标签,用于显示 Youtube 视频。
1
| {% youtube video_id [type] [cookie] %}
|
| 参数 |
说明 |
默认值 |
| video_id |
视频 ID |
无 |
| type |
视频类型 |
video |
| cookie |
是否使用 cookie |
false |
1
| {% youtube 'dQw4w9WgXcQ' %}
|
Bilibili
Bilibili 标签,用于显示 Bilibili 视频。
| 参数 |
说明 |
默认值 |
| video_id |
视频 ID |
无 |
1
| {% bvideo 'BV1B9W6eaEX1' %}
|
Audio
Audio 标签,用于显示音频。
1
| {% audio 'https://music.163.com/song/media/outer/url?id=1436709407.mp3' %}
|
Video
Video 标签,用于显示视频。
1
| {% video 'https://media.w3.org/2010/05/sintel/trailer.mp4' %}
|
Videos
Videos 标签,用于显示视频列表。
1 2
| {% videos [col] %} {% endvideos %}
|
1 2 3 4
| {% videos 2 %} {% video 'https://media.w3.org/2010/05/sintel/trailer.mp4' %} {% video 'https://media.w3.org/2010/05/bunny/trailer.mp4' %} {% endvideos %}
|
P
没错,就是 P 标签。
| 参数 |
说明 |
默认值 |
| cls |
类名 |
无 |
| content |
内容 |
无 |
cls: center, left, right, h1, h2, h3, h4, h5, h6, red, green, blue, yellow, purple, orange, gray
1
| {% p 'center h2' 'Hello World!' %}
|
Span
没错,就是 Span 标签。
1
| {% span [cls] [content] %}
|
| 参数 |
说明 |
默认值 |
| cls |
类名 |
无 |
| content |
内容 |
无 |
1
| {% span 'red h2' 'Hello World!' %}
|
Fold
折叠标签,用于显示折叠内容。
1 2 3
| {% fold 'title' open %} content {% endfold %}
|
| 参数 |
说明 |
默认值 |
| title |
标题 |
无 |
| open |
是否展开 |
不填不显示 |
1 2 3
| {% fold 'title' open %} content {% endfold %}
|
Img
图片标签,用于显示图片。
1
| {% img url [alt] [style] %}
|
| 参数 |
说明 |
默认值 |
| url |
图片链接 |
无 |
| alt |
图片描述 |
无 |
| style |
图片样式 |
无 |
1
| {% img 'https://ui.everfu.cn/5e27069a26f95747442594647fc7d8b9.png/cover' 'cover' 'width: 200px' %}
|
Inline Img
内联图片标签,用于显示内联图片。
1
| {% inline_img url [alt] [style] %}
|
| 参数 |
说明 |
默认值 |
| url |
图片链接 |
无 |
| alt |
图片描述 |
无 |
| style |
图片样式 |
无 |
1
| {% inline_img 'https://ui.everfu.cn/5e27069a26f95747442594647fc7d8b9.png/cover' 'cover' '20px' %}
|
Note
Note 标签,用于显示提示。
1 2 3
| {% note 'type' 'icon' %} content {% endnote %}
|
| 参数 |
说明 |
默认值 |
| type |
类型 |
无 |
| icon |
图标 |
无 |
type: primary, success, warning, danger, info, modern, flat, simple
icon: fantawesome 图标(例如: fas fa-mail)
1 2 3
| {% note 'danger modern' 'fas fa-wand-magic-sparkles' %} content {% endnote %}
|
Card
Card 标签,用于显示卡片。
1
| {% card 'title','url','cover','score','desc','icon','tag','width','height' %}
|
| 参数 |
说明 |
默认值 |
| title |
标题 |
无 |
| url |
链接 |
无 |
| cover |
封面 |
无 |
| score |
评分 |
无 |
| desc |
评价 |
无 |
| icon |
图标 |
无 |
| tag |
标签 |
无 |
| width |
宽度 |
无 |
| height |
高度 |
无 |
1
| {% card '诡秘之主','https://book.qidian.com/info/1010868264/','https://bookcover.yuewen.com/qdbimg/349573/1010868264/300','4.5','第一次接触这种西方文学小说,刚开始感觉看不懂,断断续续看了很多次。后来越看越觉好看,每次看甚至都需要查“文档”','fa-solid fa-book-open','小说' %}
|
第一次接触这种西方文学小说,刚开始感觉看不懂,断断续续看了很多次。后来越看越觉好看,每次看甚至都需要查“文档”查看详情 小说
Link
用于展示链接
1
| {% link 'titke' 'subtitke' 'url' %}
|
| 参数 |
说明 |
默认值 |
| title |
标题 |
无 |
| subtitke |
副标题 |
无 |
| url |
链接 |
无 |
1
| {% link 'Solitude' '一款简洁优雅并易用的 Hexo 博客主题' 'https://solitude.js.org/zh' %}
|
Checkbox
展示复选框
1
| {% checkbox 'style' 'checked' 'content' %}
|
| 参数 |
说明 |
默认值 |
| style |
样式 |
无 |
| checked |
是否选中 |
checked |
| content |
内容 |
无 |
1 2
| {% checkbox 'times red' checked '选中' %} {% checkbox 'plus blue' 'checked' '未选中' %}
|
展示按钮
Github Repo
展示 Github 仓库
1
| {% github 'everfu/hexo-theme-solitude' %}
|
Gitea Repo
展示 Gitea 仓库
1
| {% gitea 'server' 'repo' %}
|
| 参数 |
说明 |
默认值 |
| server |
服务器 |
无 |
| repo |
仓库 |
无 |
1
| {% gitea 'https://git.fsfe.org' 'FSFE/fsfe-website' %}
|
Gitee Repo
展示 Gitee 仓库
1
| {% gitee 'everfu/hexo-theme-solitude' %}
|
Gitlab Repo
展示 Gitlab 仓库
1
| {% gitlab 'gitlab-org/gitlab' %}
|
Bubble
展示气泡
1
| {% bubble 'content' 'notation' 'color' %}
|
| 参数 |
说明 |
默认值 |
| content |
内容 |
无 |
| notation |
符号 |
无 |
| color |
颜色 |
无 |
1
| {% bubble '我是一段文字内容,这是我写的东西' '我是提示文字' 'red' %}
|
Keyboard
展示键盘按键
Spoiler
展示剧透
1
| {% spoiler 'style' 'content' %}
|
| 参数 |
说明 |
默认值 |
| style |
样式 |
blur / block |
| content |
内容 |
无 |
1 2
| {% spoiler 'block' '我是一段文字内容,这是我写的东西' %} {% spoiler 'blur' '我是一段文字内容,这是我写的东西' %}
|
我是一段文字内容,这是我写的东西
我是一段文字内容,这是我写的东西