Front-matter参数
| Front-matter 参数 | 含义/功能描述 |
|---|---|
title |
文章/页面标题（必填） |
date |
文章创建日期（影响排序与时间显示） |
| updated | 文章最后修改日期（不填默认等于 date） |
tags |
文章标签（支持多个, e.g. [Hexo, Butterfly, 博客]） |
categories |
文章分类（支持多级, e.g. [技术, 前端]） |
description / desc |
文章描述, e.g. 这是一篇关于Butterfly主题的介绍… |
| keywords | SEO 关键词, 增强搜索引擎, 需要配置SEO搜索引擎优化 |
| top_img | 文章页顶部大图 |
index_img |
首页文章卡片缩略图（没填通常使用top_img, 功能与cover一致, 新版本推荐用index_img） |
sticky |
文章自定义排序（数值越大越靠前，依赖: hexo-generator-index） |
| comments | 是否开启评论（true/false，可覆盖全局设置） |
| password | 单篇文章加密（不为空即加密, 依赖: hexo-blog-encrypt) |
| highlight_shrink | 本文代码框默认是否折叠（true=折叠 / false=展开） |
| katex | 是否在本页启用 KaTeX 数学公式渲染（需主题配置按需加载） |
| mathjax | 是否在本页启用 MathJax 数学公式渲染（需主题配置按需加载） |
| toc | 是否显示本文目录（可覆盖全局设置） |
| toc_number | 目录是否显示编号（可覆盖全局设置） |
| copyright | 是否显示文章版权声明（可覆盖全局） |
| reward | 是否显示打赏二维码（可覆盖全局） |
| hide | 是否在首页/归档等列表中隐藏该文章 |
常用组合推荐
1 | --- |
全局使用
通过alias将hexo命令固定
编辑
.zshrc文件:vi ~/.zshrc1
2
3
4
5######################################
自定义命令别名
######################################
Hexo 博客快捷命令
alias hexo='cd /Users/poco/Documents/Learning/hexo-blog && hexo'立即生效:
source ~/.zshrc在任意目录下执行hexo命令都可以识别, 并自动进入到hexo-blog目录下.
导航栏自定义
执行命令, e.g. 新增视频模块
1
hexo new page video
新增文件
source/video/index.md, 编辑md文件的元信息1
2
3
4
5---
title: 视频
date: 2026-01-10 22:56:16
type: "video"
---在
_config.butterfly.yml添加配置项, 将video模块加载到导航栏菜单中1
2menu:
视频: /video/ || fas fa-video
P.S. 当导航栏中的模块过多时, 可以在menu中增加父级菜单, 实现导航栏下拉菜单功能.
1 | menu: |
效果如图:
文章加密功能
安装插件
1
npm install --save hexo-blog-encrypt
在
/blog/_config.yml文件中添加以下内容:1
2
3
4
5
6
7
8
9# 文章加密
encrypt:
enable: true
# 文章加密提示信息
hexo-blog-encrypt:
abstract: 这篇文章已被加密，需要输入密码才能查看哦~
message: Hey，这篇文章被加密了，请输入密码！
wrong_pass_message: Oh，密码错了，检查一下好吗～在想要使用加密功能的文章头部加上对应文字（仅单篇文章加密）
1
2
3---
password: 123456
---- password: 该篇文章使用的密码
- abstract: 摘要文字（少量）
- message: 密码框上的描述性文字
模块嵌入
视频模块
需要视频平台支持嵌入iframe框架, e.g. Bilibili, YouTube.
前往Hexo博客根目录，执行如下命令：
1
hexo new page video
你会找到
source/video/index.md这个文件在
[BlogRoot]\source\css\custom.css自定义样式的文件中引入如下代码（这是我的，你可以自行微调）：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16/* 哔哩哔哩视频适配 */
.aspect-ratio {
position: relative;
width: 90%;
height: auto;
padding-bottom: 75%;
margin: 3% auto;
text-align: center;
}
.aspect-ratio iframe {
position: absolute;
width: 100%;
height: 86%;
left: 0;
top: 0;
}直接复制插入你的
source/video/index.md文章就行，修改里面的 aid 为你视频的 AV号(
AV号获取方法，在网页版B站分享按钮最后一个选项，有个嵌入代码，复制插入md文件即可)：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15---
title: 视频
date: 2026-01-10 22:56:16
type: "video"
---
<div align=center class="aspect-ratio">
<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=298622138&bvid=BV17F411T7Ao&cid=25761288170&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe> scrolling="no"
border="0"
frameborder="no"
framespacing="0"
high_quality=1
danmaku=1
allowfullscreen="true">
</iframe>
</div>导航栏菜单中添加
1
2menu:
视频: /video/ || fas fa-video重启Hexo
音乐模块
创建音乐模块
1
hexo new page music
安装
hexo-tag-aplayer插件1
npm install --save hexo-tag-aplayer
找到项目文件夹根目录下的
_config.yml文件，添加如下代码：1
2
3aplayer:
meting: true
asset_inject: false之后打开
_config.butterfly.yml文件，添加模块并启用插件1
2
3
4
5
6
7
8
9# 导航菜单设置
# 说明：配置顶部导航栏的菜单项，格式为 名称: 路径 || 图标
menu:
音乐: /music/ || fas fa-music
# Inject the css and script (aplayer/meting)
aplayerInject:
enable: true
per_page: true编辑
source/music/index.md文件1
2
3
4
5
6
7---
title: 音乐
date: 2026-01-10 16:03:52
type: "music"
---
{% meting "17375390739" "netease" "playlist" "autoplay" "mutex:false" "listmaxheight:400px" "preload:none" "theme: #ad7a86" %}
MetingJS 是基于Meting API 的 APlayer
衍生播放器，引入 MetingJS 后，播放器将支持对于 QQ音乐、网易云音乐、虾米、酷狗、百度等平台的音乐播放。
server：netease（网易云音乐），tencent（QQ音乐），kugou（酷狗音乐），xiami（虾米音乐），baidu（百度音乐）。type：song（歌曲），playlist（歌单），album（专辑），search（搜索关键字），artist（歌手）。添加单曲选的歌曲，歌单选择playlist，可以自行尝试。- id：就是在网页版上自己歌单的ID号，但是需要注意的是歌单中不能包含VIP音乐，不然无法播放。建议使用网易云音乐。
有关
{% meting %}的选项列表如下:
| 选项 | 默认值 | 描述 |
|---|---|---|
| id | 必填 | 歌曲 id / 播放列表 id / 相册 id / 搜索关键字 |
| server | 必填 | 音乐平台: netease, tencent, kugou, xiami, baidu |
| type | 必填 | song, playlist, album, search, artist |
| fixed | false |
开启固定模式 |
| mini | false |
开启迷你模式 |
| loop | all |
列表循环模式：all, one,none |
| order | list |
列表播放模式： list, random |
| volume | 0.7 | 播放器音量 |
| lrctype | 0 | 歌词格式类型 |
| listfolded | false |
指定音乐播放列表是否折叠 |
| storagename | metingjs |
LocalStorage 中存储播放器设定的键名 |
| autoplay | true |
自动播放，移动端浏览器暂时不支持此功能 |
| mutex | true |
该选项开启时，如果同页面有其他 aplayer 播放，该播放器会暂停 |
| listmaxheight | 340px |
播放列表的最大长度 |
| preload | auto |
音乐文件预载入模式，可选项： none, metadata, auto |
| theme | #ad7a86 |
播放器风格色彩设置 |
全局吸底Aplayer模式
在
_config.butterfly.yml文件中修改如下：1
2
3
4inject:
head:
bottom:
- <div class="aplayer no-destroy" data-id="17375390739" data-server="netease" data-type="playlist" data-fixed="true" data-autoplay="true" data-lrcType="-1"> </div>如果想切换页面时，音乐不会中断，就在
_config.butterfly.yml文件中 pjax修改为true1
2
3pjax:
enable: ture
exclude:
照片模块
照片模块整理为两部分: 照片主页面, 照片详情页
创建照片主页面模块
1
hexo new page wallpaper
之后打开
_config.butterfly.yml文件，添加照片模块1
2menu:
照片: /wallpaper/ || fas fa-image编辑
/wallpaper/index.md文件1
2
3
4
5
6
7
8
9
10---
title: 照片
date: 2026-01-11 21:56:59
type: "wallpaper"
---
<div class="gallery-group-main">
{% galleryGroup '自然｜风景' '绝美的自然风景桌面壁纸~' '/wallpaper/nature' https://cdn.jsdelivr.net/gh/koco-co/picgo-images/picgo-images/文章随机封面03.png %}
{% galleryGroup '动漫｜二次元' '动漫高清桌面壁纸~' '/wallpaper/anime' https://cdn.jsdelivr.net/gh/koco-co/picgo-images/picgo-images/二次元人物07.png %}
</div>外挂标签
{% galleryGroup %}的模版:{% galleryGroup name description link img-url %}, 参数解释如下:- name：照片名称
- description：描述信息
- link：链接到对应相册的子页面地址
- img-url：分类封面地址
创建照片模块子页面
1
2hexo new page nature
hexo new page anime但是现在
/source/wallpaper/index.md与/source/nature/index.md是平级的，所以要将/nature 和 /anime整个文件夹复制到/wallpaper，这样就可以实现跳转了。(注: 不需要在_config.butterfly.yml的menu中添加子页面模块)编辑子页面的index.md文件
/nature1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22---
title: 自然｜风景
date: 2026-01-11 22:20:11
type: "nature"
---
{% gallery %}
{% endgallery %}/anime1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21---
title: 动漫｜二次元
date: 2026-01-11 22:20:21
type: "anime"
---
{% gallery %}
{% endgallery %}
信笺样式留言板
⚠️
不需要执行命令: hexo new page comments
在
[Blogroot]运行指令1
npm install hexo-butterfly-envelope --save
在
_config.butterfly.yml添加配置项（两者任选其一）1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20# envelope_comment
# see https://akilar.top/posts/e2d3c450/
envelope_comment:
enable: true #控制开关
custom_pic:
cover: https://npm.elemecdn.com/hexo-butterfly-envelope/lib/violet.jpg #信笺头部图片
line: https://npm.elemecdn.com/hexo-butterfly-envelope/lib/line.png #信笺底部图片
beforeimg: https://npm.elemecdn.com/hexo-butterfly-envelope/lib/before.png # 信封前半部分
afterimg: https://npm.elemecdn.com/hexo-butterfly-envelope/lib/after.png # 信封后半部分
message: #信笺正文，多行文本，写法如下
- 有什么想问的？
- 有什么想说的？
- 有什么想吐槽的？
- 哪怕是有什么想吃的，都可以告诉我哦~
bottom: 自动书记人偶竭诚为您服务！ #仅支持单行文本
height: #1050px，信封划出的高度
path: #【可选】comments 的路径名称。默认为 comments，生成的页面为 comments/index.html
front_matter: #【可选】comments页面的 front_matter 配置
title: 留言板
comments: true添加到导航栏菜单
1
2menu:
留言板: /comments/ || fas fa-comments
Twikoo评论系统
在Butterfly主题中, 集成Twikoo评论系统, 实现评论功能.
有自己的服务器, 使用docker部署,
Ref. 【docker】为 Hexo 添加评论系统 | Twikoo 的部署与使用没有服务器, 使用免费的 Vercel 部署,
Ref. 【Vercel】Twikoo | 为你的 HEXO 加入评论系统
CDN替换
主题默认的CDN有：local、cdnjs、jsdelivr、unpkg等，但是速度比较一般，要想提高部分标准静态资源的响应速度，走CDN是最好的办法，最好是在国内的CDN。
参考教程：
修改主题配置文件_config.butterfly.yml的CDN配置项：
1 | # CDN |
修改完成后可以 f12->源代码->网页 看看是否已经加载到对应的资源
SEO搜索引擎优化
SEO 是由英文 Search Engine Optimization 缩写而来，中文意译为“搜索引擎优化”。SEO 是指通过站内优化比如网站结构调整、网站内容建设、网站代码优化等以及站外优化。
登录谷歌搜索控制台，添加网站
有两种登录方式，推荐使用第一种
第一种验证方式，选择右边网址前缀，添加域名
https://koco-co.github.io，选择html文件验证，将下载文件放在themes/butterfly/source下。在_config.yml中，添加忽略编译的文件，如下：1
2
3
4skip_render:
- baidu_verify_codexxxxxxxxxxxx.html
- googlexxxxxxx.html
- BingSitexxxxxxx.xml第二种验证方式，选择左边通过域名的dns解析，按照网页提示即可完成.
点击左侧
站点地图，添加文件https://koco-co.github.io/baidusitemap.xml，点击提交，然后看状态为成功即可。
Bing
进入必应搜索控制台，网站验证、添加站点地图，与google收录一致。
相关推荐
2026-01-09
Github文档(二) 博客搭建
从零开始搭建 Hexo 博客，配置 Butterfly 主题，使用 GitHub Actions 实现自动部署。详细介绍环境准备、主题配置、插件安装和自动化部署的完整流程。
2026-01-13
Butterfly文档(三) 标签外挂
Butterfly 标签外挂完整教程，涵盖 Note、Tabs、Folding、Button、Gallery、Mermaid 等所有外挂标签的用法和配置。
2026-01-10
Butterfly文档(一) 主题美化
Butterfly 主题美化教程，涵盖背景一图流、霓虹灯特效、透明页脚、字体设置、侧边栏美化等全方位自定义配置。
评论
