📖 本教程更新于 2022 年 08 月 18 日，教程的内容针对最新稳定版而更新（如果你是旧版，教程会有些出入，请留意）

🦋 Butterfly 已经更新到 4.4.0

语言

修改站点配置文件 _config.yml

默认语言是 en

主题支持三种语言

• default(en)

• zh-CN (简体中文)

• zh-TW (繁体中文)

网站资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，请修改博客根目录的_config.yml

导航菜单

修改 主题配置文件

必须是 /xxx/，后面||分开，然后写图标名。

如果不希望显示图标，图标名可不写。

默认子目录是展开的，如果你想要隐藏，在子目录里添加 hide 。

注意： 导航的文字可自行更改

例如：

代码

代码块中的所有功能只适用于 Hexo 自带的代码渲染

如果使用第三方的渲染器，不一定会有效

代码高亮主题

Butterfly 支持 6 种代码高亮样式：

• darker

• pale night

• light

• ocean

• mac

• mac light

修改 主题配置文件

主题从 3.0 开始，支持使用自定义的代码颜色。

如何自定义主题，请查看下面这篇文章。

自定義代碼配色

代码复制

主题支持代码复制功能

修改 主题配置文件

代码框展开 / 关闭

在默认情况下，代码框自动展开，可设置是否所有代码框都关闭状态，点击>可展开代码

• true 全部代码框不展开，需点击>打开

• false 代码框展开，有>点击按钮

• none 不显示>按钮

修改 主题配置文件

你也可以在 post/page 页对应的 markdown 文件 front-matter 添加 highlight_shrink 来独立配置。

當主题配置文件中的 highlight_shrink 设为 true 时，可在 front-matter 添加highlight_shrink: false来单独配置文章展开代码框。

當主题配置文件中的 highlight_shrink 设为 false 时，可在 front-matter 添加highlight_shrink: true来单独配置文章收缩代码框。

highlight_shrink: true

highlight_shrink: false

highlight_shrink: none

代码换行

在默认情况下，Hexo 在编译的时候不会实现代码自动换行。如果你不希望在代码块的区域里有横向滚动条的话，那么你可以考虑开启这个功能。

修改 主题配置文件

如果你是使用 highlight 渲染，需要找到你站点的 Hexo 配置文件_config.yml，将line_number改成false:

如果你是使用 prismjs 渲染，需要找到你站点的 Hexo 配置文件_config.yml，将line_number改成false:

代码高度限制

可配置代码高度限制，超出的部分会隐藏，并显示展开按钮。

注意：

1. 单位是 px，直接添加数字，如 200

1. 实际限制高度为 highlight_height_limit + 30 px ，多增加 30px 限制，目的是避免代码高度只超出 highlight_height_limit 一点时，出现展开按钮，展开没内容。

1. 不适用于隐藏后的代码块（ css 设置 display: none）

社交图标

Butterfly 支持 font-awesome v6 图标

书写格式 图标名：url || 描述性文字

图标名可在这寻找

PC:

Mobile:

主页文章节选 (自动节选和文章页 description)

因为主题 UI 的关系，主页文章节选只支持自动节选和文章页description。

在butterfly里，有四种可供选择

1. description： 只显示 description

1. both： 优先选择 description，如果没有配置 description，则显示自动节选的内容

1. auto_excerpt：只显示自动节选

1. false： 不显示文章内容

修改 主题配置文件

description在 front-matter 里添加

顶部图

如果不要显示顶部图，可直接配置 disable_top_img: true配置中的值：

其它页面 （tags/categories / 自建页面）和 文章页的 top_img ，请到对应的 md 页面设置front-matter中的top_img

以上所有的 top_img 可配置以下值

tag_per_img 和 category_per_img 是 3.2.0 新增的内容，可对 tag 和 category 进行单独的配置

并不推荐为每个 tag 和每个 category 都配置不同的顶部图，因为配置太多会拖慢生成速度

文章置顶

【推荐】[hexo-generator-index](https://github.com/hexojs/hexo-generator-index)从 2.0.0 开始，已经支持文章置顶功能。你可以直接在文章的front-matter区域里添加sticky: 1属性来把这篇文章置顶。数值越大，置顶的优先级越大。

文章封面

文章的 markdown 文档上, 在Front-matter添加cover, 并填上要显示的图片地址。 如果不配置cover, 可以设置显示默认的 cover.

如果不想在首页显示 cover, 可以设置为false

修改 主题配置文件

当配置多张图片时, 会随机选择一张作为 cover. 此时写法应为

文章页相关配置

文章 meta 显示

这个选项是用来显示文章的相关信息的。

修改 主题配置文件

date_format 是 3.2.0 新增的内容，配置时间显示明确时间还是相对时间

文章版权

为你的博客文章展示文章版权和许可协议。

修改 主题配置文件

由于Hexo 4.1 开始，默认对网址进行解码，以至于如果是中文网址，会被解码，可设置 decode: true来显示中文网址。

如果有文章（例如：转载文章）不需要显示版权，可以在文章 Front-matter 单独设置

从3.0.0开始，支持对单独文章设置版权信息，可以在文章 Front-matter 单独设置

版权显示截图

文章打赏

在你每篇文章的结尾，可以添加打赏按钮。相关二维码可以自行配置。

对于没有提供二维码的，可配置一张软件的 icon 图片，然后在 link 上添加相应的打赏链接。用户点击图片就会跳转到链接去。

link 可以不写，会默认为图片的链接。

修改 主题配置文件

TOC

在文章页，会有一个目录，用于显示 TOC。

修改 主题配置文件

— | — |

为特定的文章配置

在你的文章md文件的头部，加入toc_number和toc，并配置true或者false即可。

主题会优先判断文章 Markdown 的 Front-matter 是否有配置，如有，则以 Front-matter 的配置为准。否则，以主题配置文件中的配置为准

相关文章

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

修改 主题配置文件

文章锚点

开启文章锚点后，当你在文章页进行滚动时，文章链接会根据标题 ID 进行替换 (注意: 每替换一次，会留下一个历史记录。所以如果一篇文章有很多锚点的话，网页的历史记录会很多。)

修改 主题配置文件

文章过期提醒

可设置是否显示文章过期提醒，以更新时间为基准。

limit_day： 距离更新时间多少天才显示文章过期提醒

message_prev ： 天数之前的文字

message_next：天数之後的文字

文章编辑按钮

在文章标题旁边显示一个编辑按钮，点击会跳转到对应的链接去。

文章分页按钮

可设置分页的逻辑，也可以关闭分页显示

头像

修改 主题配置文件

图片描述

可开启图片 Figcaption 描述文字显示

优先显示图片的 title 属性，然后是 alt 属性

修改 主题配置文件

复制相关配置

可配置网站是否可以复制、复制的内容是否添加版权信息

博客年份

since是一个来展示你站点起始时间的选项。它位于页面的最底部。

修改 主题配置文件

页脚自定义文本

custom_text是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等。支持HTML。

修改 主题配置文件

对于部分人需要写 ICP 的，也可以写在 custom_text里

右下角按钮

简繁转换

简体繁体互换

右下角会有简繁转换按钮。

修改 主题配置文件

夜间模式

右下角会有夜间模式按钮

修改 主题配置文件

V2.0.0 开始增加一个选项，可开启自动切换 light mode 和 dark mode

autoChangeMode: 1 跟随系统而变化，不支持的浏览器 / 系统将按照时间晚上 6 点到早上 6 点之间切换为 dark mode

autoChangeMode: 2 只按照时间 晚上 6 点到早上 6 点之间切换为 dark mode, 其余时间为 light mode

autoChangeMode: false 取消自动切换

阅读模式

阅读模式下会去掉除文章外的内容，避免干扰阅读。

只会出现在文章页面，右下角会有阅读模式按钮。

修改 主题配置文件

按钮排序

注意： 不要重复

侧边栏设置

侧边排版

可自行决定哪个项目需要显示，可决定位置，也可以设置不显示侧边栏。

修改 主题配置文件

访问人数 busuanzi (UV 和 PV)

访问 busuanzi 的官方網站查看更多的介绍。

修改 主题配置文件

运行时间

网页已运行时间

修改 主题配置文件

最新评论

最新评论只会在刷新时才会去读取，并不会实时变化

由于 API 有 访问次数限制，为了避免调用太多，主题默认存取期限为 10 分钟。也就是说，调用后资料会存在 localStorage 里，10 分钟内刷新网站只会去 localStorage 读取资料。 10 分钟期限一过，刷新页面时才会去调取 API 读取新的数据。 （ 3.6.0 新增了 storage 配置，可自行配置缓存时间）

在侧边栏显示最新评论板块

修改 主题配置文件

部分配置解釋：

标签外挂（Tag Plugins）

标签外挂是 Hexo 独有的功能，并不是标准的 Markdown 格式。

以下的写法，只适用于 Butterfly 主题，用在其它主题上不会有效果，甚至可能会报错。使用前请留意

标签外挂虽然能为主题带来一些额外的功能和 UI 方面的强化，但是，标签外挂也有明显的限制，使用时请留意。

Note (Bootstrap Callout)

移植于 next 主题，并进行修改。

修改 主题配置文件

icons和light_bg_offset只对_方法一_生效

Note 标签外挂有两种用法

— | — |

Gallery 相册图库

一个图库集合。

写法

例如：

Gallery 相册

区别于旧版的 Gallery 相册, 新的 Gallery 相册会自动根据图片长度进行排版，书写也更加方便，与 markdown 格式一样。可根据需要插入到相应的 md。

写法:

例如

tag-hide

2.2.0 以上提供

请注意，tag-hide 内的标签外挂 content 内都不建议有 h1 - h6 等标题。因为 Toc 会把隐藏内容标题也显示出来，而且当滚动屏幕时，如果隐藏内容没有显示出来，会导致 Toc 的滚动出现异常。

如果你想把一些文字、内容隐藏起来，并提供按钮让用户点击显示。可以使用这个标签外挂。

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

( content 不能包含英文逗号，可用‚)

哪个英文字母最酷？因为西装裤 (C 装酷)

门里站着一个人? 闪

block独立的 block 隐藏内容，可以隐藏很多内容，包括图片，代码块等等

( display 不能包含英文逗号，可用‚)

查看答案

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

( display 不能包含英文逗号，可用‚)

mermaid

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

修改 主题配置文件

写法：

例如：

Tabs

移植于 next 主题

使用方法

Button

使用方法：

This is my website, click the button Butterfly This is my website, click the button Butterfly This is my website, click the button Butterfly This is my website, click the button Butterfly This is my website, click the button Butterfly

Butterfly Butterfly Butterfly

more than one button in center

Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly Butterfly

inlineImg

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

label

高亮所需的文字

臣亮言：先帝 创业未半，而中道崩殂 。今天下三分，益州疲敝 ，此诚危急存亡之秋 也！然侍卫之臣，不懈于内；忠志之士 ，忘身于外者，盖追先帝之殊遇，欲报之于陛下也。诚宜开张圣听，以光先帝遗德，恢弘志士之气；不宜妄自菲薄，引喻失义，以塞忠谏之路也。

宫中、府中，俱为一体；陟罚臧否，不宜异同。若有作奸 、犯科 ，及为忠善者，宜付有司，论其刑赏，以昭陛下平明之治；不宜偏私，使内外异法也。

timeline

flink

可在任何界面插入类似友情链接列表效果

内容格式与友情链接界面一样，支持 yml 格式

Prev

网站建设文档(四) butterfly主題配置和美化超详细 - 2

Next

网站建设文档(二) 添加子页面和页面内容编辑