Butterfly主题基础装修

1.快速开始

在Hexo的根目录

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

修改 Hexo 根目录下的 _config.yml​，把主题改为 butterfly​

1
theme: butterfly

安装插件

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

在 hexo 的根目录创建一个文件 _config.butterfly.yml​，并把主题目录的 _config.yml ​内容复制到 _config.butterfly.yml​ 去。

2. 主题页面

2.1 Front-matter

Front-matter 是 markdown 文件最上方以 — 分隔的区域，用于指定个别档案的变数。

​Page Front-matter​ 用于 页面​ 配置
​Post Front-matter​ 用于 文章页​ 配置

1.Page Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
title:
date:
updated:
type:
comments:
description:
keywords:
top_img:
mathjax:
katex:
aside:
aplayer:
highlight_shrink:
random:
limit:
  type:
  value:
参数 解释
title 【必需】页面标题
date 【必需】页面创建日期
type 【必需】标签、分类和友情链接三个页面需要配置
updated 【可选】页面更新日期
description 【可选】页面描述
keywords 【可选】页面关键字
comments 【可选】显示页面评论模块 (默认 true)
top_img 【可选】页面顶部图片
mathjax 【可选】显示 mathjax (当设置 mathjax 的 per_page: false 时，才需要配置，默认 false)
katex 【可选】显示 katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false)
aside 【可选】显示侧边栏 (默认 true)
aplayer 【可选】在需要的页面加载 aplayer 的 js 和 css,请参考文章下面的音乐 配置
highlight_shrink 【可选】配置代码框是否展开 (true/false) (默认为设置中 highlight_shrink 的配置)
random 【可选】配置友情链接是否随机排序（默认为 false）
limit 【可选】配置説説显示数量
limit.type 【可选】配置説説显示数量的类型 （date 或者 num）
limit.value 【可选】配置説説显示数量的值

2.Post Front-matter

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
---
title:
date:
updated:
tags:
categories:
keywords:
description:
top_img:
comments:
cover:
toc:
toc_number:
toc_style_simple:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
mathjax:
katex:
aplayer:
highlight_shrink:
aside:
abcjs:
noticeOutdate:
---
写法 解释
title 【必需】文章标题
date 【必需】文章创建日期
updated 【可选】文章更新日期
tags 【可选】文章标签
categories 【可选】文章分类
keywords 【可选】文章关键字
description 【可选】文章描述
top_img 【可选】文章顶部图片
cover 【可选】文章缩略图(如果没有设置 top_img,文章页顶部将显示缩略图，可设为 false/图片地址/留空)
comments 【可选】显示文章评论模块(默认 true)
toc 【可选】显示文章 TOC(默认为设置中 toc 的 enable 配置)
toc_number 【可选】显示 toc_number(默认为设置中 toc 的 number 配置)
toc_style_simple 【可选】显示 toc 简洁模式
copyright 【可选】显示文章版权模块(默认为设置中 post_copyright 的 enable 配置)
copyright_author 【可选】文章版权模块的文章作者
copyright_author_href 【可选】文章版权模块的文章作者链接
copyright_url 【可选】文章版权模块的文章连结链接
copyright_info 【可选】文章版权模块的版权声明文字
mathjax 【可选】显示 mathjax(当设置 mathjax 的 per_page: false 时，才需要配置，默认 false )
katex 【可选】显示 katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false )
aplayer 【可选】在需要的页面加载 aplayer 的 js 和 css,请参考文章下面的音乐 配置
highlight_shrink 【可选】配置代码框是否展开(true/false)(默认为设置中 highlight_shrink 的配置)
aside 【可选】显示侧边栏 (默认 true)
abcjs 【可选】加载 abcjs (当设置 abcjs 的 per_page: false 时，才需要配置，默认 false )
noticeOutdate 【可选】文章过期提醒 (默认为设置中 noticeOutdate 的 enable 配置)

2.2 标签页

  1. 前往 Hexo 的根目录
  2. 输入 hexo new page tags​
  3. 会生成 source/tags/index.md​ 文件
  4. 修改这个文件：
1
2
3
4
5
6
7
8
---
title: 标签
date: 2025-01-06 13:46:58
type: 'tags'
orderby: length
order: -1

---
参数 解释
type 【必须】页面类型，必须为 tags
orderby 【可选】排序方式：random - 随机排序 / name - 标签名字排序 / length - 标签数量排序
order 【可选】排序次序：1（升序），-1（降序）

2.3 分类页

  1. 前往 Hexo 的根目录
  2. 输入 hexo new page categories​
  3. 找到 source/categories/index.md​ 这个文件
  4. 修改这个文件：
1
2
3
4
5
6
---
title: 分类
date: 2018-01-05 00:00:00
type: 'categories'

---

2.4 链接页面

  1. 前往你的 Hexo​的根目录
  2. 输入 hexo new page link​
  3. 你会找到 source/link/index.md​ 这个文件
  4. 修改这个文件：
1
2
3
4
5
6
---
title: 链接
date: 2025-01-06 14:12:04
type: 'link'

---

在 Hexo 根目录中的 source/_data​（如果没有 _data 文件夹，请自行创建），创建一个文件 link.yml​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- class_name: 网站
  class_desc: 常用网站
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: 视频网站
    - name: Weibo
      link: https://www.weibo.com/
      avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
      descr: 中国最大社交分享平台
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: 社交分享平台

​class_name​ 和 class_desc​ 支持 html 格式书写，如不需要，也可以留空。

2.5 图库

图库页面只是普通的页面，你只需要hexo n page xxxxx​创建你的页面就行

然后使用标签外挂 galleryGroup，具体用法请查看对应的内容。

1
2
3
4
5
<div class="gallery-group-main">
{% galleryGroup '壁纸' '收藏的一些壁纸' '/Gallery/wallpaper' https://i.loli.net/2019/11/10/T7Mu8Aod3egmC4Q.png %}
{% galleryGroup '漫威' '关于漫威的图片' '/Gallery/marvel' https://i.loli.net/2019/12/25/8t97aVlp4hgyBGu.jpg %}
{% galleryGroup 'OH MY GIRL' '关于OH MY GIRL的图片' '/Gallery/ohmygirl' https://i.loli.net/2019/12/25/hOqbQ3BIwa6KWpo.jpg %}
</div>

2.6 404页面

主题内置了一个简单的 404 页面，可在设置中开启。

1
2
3
4
5
# A simple 404 page
error_404:
  enable: true
  subtitle: "啊噢，页面走丢了！"
  background: /img/404-error.png

3. 主题配置

3.1 语言

修改 Hexo 的配置文件 _config.yml​

默认语言是en​

主题支持

  • default(en)
  • zh-CN (简体中文)
  • zh-TW (台湾繁体中文)
  • zh-HK (香港繁体中文)
  • ja (日语)
  • ko (韩语)

3.2 网站资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，请修改 Hexo 的_config.yml​

1
2
3
4
5
6
7
8
# Site
title: Somongbeom's Blog
subtitle: '极繁主义者'
description: ''
keywords:
author: Somongbeom
language: zh-CN
timezone: ''

3.3 导航

3.3.1参数设置

1
2
3
4
5
6
nav:
  # Navigation bar logo image
  logo: /themes/butterfly/source/img/web.png
  display_title: true
  # Whether to fix navigation bar
  fixed: false
参数 解释
logo 网站的 logo，支持图片，直接填入图片链接
display_title 是否显示网站标题，填写 true 或者 false
fixed 是否固定状态栏，填写 true 或者 false

3.3.2 目录

1
2
3
4
5
6
7
8
9
10
11
menu:
  首页: / || fas fa-home
  时间轴: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  # 清单||fa fa-heartbeat:
  #   音乐: /music/ || fas fa-music
  #   照片: /Gallery/ || fas fa-images
  #   电影: /movies/ || fas fa-video
  链接: /link/ || fas fa-link
  关于: /about/ || fas fa-heart

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

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

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

1
2
3
List||fas fa-list||hide:
  Music: /music/ || fas fa-music
  Movie: /movies/ || fas fa-video

3.4 代码块

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# --------------------------------------
# Code Blocks Settings
# --------------------------------------
code_blocks:
  # Code block theme: darker / pale night / light / ocean / false
  theme: ocean
  macStyle: true
  # Code block height limit (unit: px)
  height_limit: 230
  word_wrap: true
  # Toolbar
  copy: true
  language: true
  # true: shrink the code blocks | false: expand the code blocks | none: expand code blocks and hide the button
  shrink: false
  fullpage: false
参数 解释
theme 代码高亮主题，可选 darker / pale night / light / ocean / false
macStyle 是否使用 Mac 风格
height_limit 代码块高度限制（单位: px），可填写 数字 或者 false
word_wrap 是否自动换行
copy 是否显示复制按钮
language 是否显示语言标签
shrink true: 收缩代码块 / false: 展开代码块 / none: 展开代码块并隐藏按钮
fullpage 是否全屏显示代码块

3.5 社交图标

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

1
2
3
social:
  fab fa-github: https://github.com/Somongbeom || Github || "#FFFFFF"
  #fas fa-envelope: mailto:xxxxxx@gmail.com || Email || "#000000"

3.6 图片设置

3.6.1 头像

1
2
3
avatar:
  img: /img/touxiang.jpg
  effect: false # true：头像会一直转圈

3.6.2 顶部图

如果不要显示顶部图，可直接配置 disable_top_img: true​

顶部图的获取顺序，如果都没有配置，则不显示顶部图。

1.页面顶部图的获取顺序：

各自配置的 top_img​ > 配置文件的 default_top_img​

2.文章页顶部图的获取顺序：

各自配置的 top_img > cover​ > 配置文件的 default_top_img​

配置 解释
index_img 主页的 top_img
default_top_img 默认的 top_img，当页面的 top_img 没有配置时，会显示 default_top_img
archive_img 归档页面的 top_img
tag_img tag 子页面的默认 top_img
tag_per_img tag 子页面的 top_img，可配置每个 tag 的 top_img
category_img category 子页面的默认 top_img
category_per_img category 子页面的 top_img，可配置每个 category 的 top_img

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

配置的值 效果
留空 显示默认的 top_img（如有），否则显示默认的颜色（文章页 top_img 留空的话，会显示 cover 的值）
img 链接 图片的链接，显示所配置的图片
颜色 (HEX 值 - #0000FF,# RGB 值 - rgb(0,0,255), 颜色单词 - orange, 渐变色 - linear-gradient(135deg, #E2B0FF# 10%, #9F44D3# 100%)) 对应的颜色
transparent 透明
false 不显示 top_img

3.6.3 网站背景

默认显示白色，可设置图片或者颜色

1
2
3
# 颜色（HEX值/RGB值/顔色单词/渐变色)
# 留空 不显示背景
background: /img/background.jpg

3.7 页面 meta 显示

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
post_meta:
  # Home Page
  page:
    # Choose: created / updated / both
    date_type: both
    # Choose: date / relative
    date_format: date
    categories: true
    tags: true
    label: true
  post:
    # Choose: left / center
    position: center
    # Choose: created / updated / both
    date_type: both
    # Choose: date / relative
    date_format: date
    categories: true
    tags: true
    label: true

主页：

​image​

参数 解释
date_type 显示文章的时间，可选 created / updated / both
date_format 配置时间显示明确时间还是相对时间，可选 date / relative
categories 是否显示文章的分类
tags 是否显示文章的标签
label 是否显示文字标签

文章页：

参数 解释
position 文章页 meta 显示的位置，可选 left​（左侧）或 center​（居中）
date_type 显示文章的时间类型，可选 created​（创建时间）、updated​（更新时间）或 both​（两者都显示）
date_format 配置时间显示格式，可选 date​（显示明确时间）或 relative​（显示相对时间）
categories 是否显示文章的分类，可选 true​（显示）或 false​（不显示）
tags 是否显示文章的标签，可选 true​（显示）或 false​（不显示）
label 是否显示文字标签，可选 true​（显示）或 false​（不显示）

​image​

3.8 文章页

3.8.1 TOC 目录

在侧边栏显示 TOC（文章目录）

1
2
3
4
5
6
7
8
toc:
  post: true
  page: false
  number: true
  expand: true
  # Only for post
  style_simple: true
  scroll_percent: true

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

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

3.8.2 文章版权

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

1
2
3
4
5
6
7
8
9
10
11
post_copyright:
  # 是否启用版权声明
  enable: true
  # 是否进行文章 URL 解码
  decode: false
  # 作者链接
  author_href:
  # 许可证类型
  license: CC BY-NC-SA 4.0
  # 许可证链接
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
1
2
3
4
5
6
7
#文章版权
post_copyright:
  enable: true
  decode: false
  author_href: Somongbeom
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

3.8.3 相关文章

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

1
2
3
4
5
6
7
# Related Articles
related_post:
  enable: true
  # Number of posts displayed
  limit: 3 # 显示推荐文章数目
  # Choose: created / updated
  date_type: created  # or created or updated 文章日期显示创建日或者更新日

3.8.4 文章分页按钮

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

1
2
3
4
5
6
# post_pagination (分页)
# value: 1 || 2 || false
# 1: The 'next post' will link to old post
# 2: The 'next post' will link to new post
# false: disable pagination
post_pagination: false
参数 解释
​post_pagination: false​ 关闭分页按钮
​post_pagination: 1​ 下一篇显示的是旧文章
​post_pagination: 2​ 下一篇显示的是新文章

3.9 页脚

博客年份

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

页脚自定义文本

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

1
2
3
4
5
6
7
footer:
  owner:
    enable: true
    since: 2024
  custom_text: 我们一同喜欢着现在!
  # Copyright of theme and framework
  copyright: true

3.10 侧边栏（Aside）

侧边栏的配置

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
# --------------------------------------
# Aside Settings 侧边栏
# --------------------------------------

aside:
  enable: true
  hide: false
  # Show the button to hide the aside in bottom right button
  button: true
  mobile: true
  # Position: left / right
  position: left
  display:
    archive: true
    tag: true
    category: true
  card_author:
    enable: true
    description: 极繁主义者！
    button:
      enable: true
      icon: fab fa-github
      text: Follow Me
      link: https://github.com/Somongbeom
  card_announcement:
    enable: false
    content: 我们一同喜欢着现在！
  card_recent_post:
    enable: true
    # If set 0 will show all
    limit: 2
    # Sort: date / updated
    sort: update
    sort_order:
  card_newest_comments:
    enable: false
    sort_order:
    limit: 3
    # Unit: mins, save data to localStorage
    storage: 10
    avatar: true
  card_categories:
    enable: true
    # If set 0 will show all
    limit: 8
    # Choose: none / true / false
    expand: none
    sort_order:
  card_tags:
    enable: true
    # If set 0 will show all
    limit: 40
    color: false
    # Order of tags, random/name/length
    orderby: length
    # Sort of order. 1, asc for ascending; -1, desc for descending
    order: -1
    sort_order:
  card_archives:
    enable: true
    # Type: monthly / yearly
    type: monthly
    # Eg: YYYY年MM月
    format: MMMM YYYY
    # Sort of order. 1, asc for ascending; -1, desc for descending
    order: -1
    # If set 0 will show all
    limit: 8
    sort_order:
  card_post_series:
    enable: true
    # The title shows the series name
    series_title: false
    # Order by title or date
    orderBy: 'date'
    # Sort of order. 1, asc for ascending; -1, desc for descending
    order: -1
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order:
    # Time difference between publish date and now
    # Formal: Month/Day/Year Time or Year/Month/Day Time
    # Leave it empty if you don't enable this feature
    runtime_date:
配置 解释
enable 是否启用侧边栏
hide 是否默认隐藏侧边栏
button 是否显示隐藏侧边栏的按钮
mobile 是否在移动端显示侧边栏
position 侧边栏位置，可选 left​ 或 right​
display.archive archive 页面是否显示 aside
display.tag tag 页面是否显示 aside
display.category category 页面是否显示 aside
card_author.enable 是否显示作者卡片
card_author.description 作者描述信息
card_author.button.enable 是否显示按钮
card_author.button.icon 按钮图标，可在这里找到图标名称：Font Awesome Icons
card_author.button.text 按钮文字
card_author.button.link 按钮链接
card_announcement.enable 是否显示公告卡片
card_announcement.content 公告内容（可使用 HTML 标签）
card_recent_post.enable 是否显示最新文章卡片
card_recent_post.limit 显示文章数目，0 为全部
card_recent_post.sort 排序方式，可选 date​ 或 updated​
card_newest_comments.enable 是否显示最新评论卡片
card_newest_comments.limit 显示评论数目，0 为全部
card_newest_comments.storage 保存时间，单位分钟，保存到本地存储，避免每次刷新都重新请求数据
card_newest_comments.avatar 是否显示头像
card_categories.enable 是否显示分类卡片
card_categories.limit 显示分类数目，0 为全部
card_categories.expand 是否展开分类，可选 none​、true​ 或 false​
card_tags.enable 是否显示标签卡片
card_tags.limit 显示标签数目，0 为全部
card_tags.color 是否显示标签颜色
card_tags.orderby 标签排序方式，可选 random​、name​ 或 length​
card_tags.order 排序方式，1 为升序，-1 为降序
card_archives.enable 是否显示归档卡片
card_archives.type 归档类型，可选 monthly​ 或 yearly​
card_archives.format 归档显示格式，例如：YYYY 年 MM 月​
card_archives.order 排序方式，1 为升序，-1 为降序
card_archives.limit 显示归档数目，0 为全部
card_post_series.enable 是否显示文章系列卡片
card_post_series.series_title 是否显示系列名称
card_post_series.orderBy 排序方式，可选 title​ 或 date​
card_post_series.order 排序方式，1 为升序，-1 为降序
card_webinfo.enable 是否显示网站信息卡片
card_webinfo.post_count 是否显示文章数量
card_webinfo.last_push_date 是否显示最后更新日期
card_webinfo.runtime_date 显示网站运行时间，不需要开启，留空白就行（开启格式一定要是 Month/Day/Year Time 或者 Year/Month/Day Time）

3.11 全局配置

3.11.1 复制相关配置

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

1
2
3
4
5
6
copy:
  enable: true
  # Add the copyright information after copied content
  copyright:
    enable: true
    limit_count: 150

3.11.2 字数统计

开启字数统计功能，需要安装hexo-wordcount​插件

在 hexo 工作目录下运行 npm install hexo-wordcount --save​ or yarn add hexo-wordcount​

1
2
3
4
5
6
7
8
9
# Need to install the hexo-wordcount plugin
wordcount:
  enable: false
  # Display the word count of the article in post meta
  post_wordcount: true
  # Display the time to read the article in post meta
  min2read: true
  # Display the total word count of the website in aside's webinfo
  total_wordcount: true

3.12 Math 数学

开启 KaTeX 需要把use​设置为 katex​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
math:
  # Choose: mathjax, katex
  # Leave it empty if you don't need math
  use: katex
  per_page: true
  hide_scrollbar: false

  mathjax:
    # Enable the contextual menu
    enableMenu: true
    # Choose: all / ams / none, This controls whether equations are numbered and how
    tags: none

  katex:
    # Enable the copy KaTeX formula
    copy_tex: true

你不需要添加 katex.min.js 来渲染数学方程。相应的你需要卸载你之前的 hexo 的 markdown 渲染器，然后安装其它插件。

卸载掉 marked 插件，安装 hexo-renderer-markdown-it

1
2
3
4
5
npm un hexo-renderer-marked --save # 如果有安装这个的话，卸载
npm un hexo-renderer-kramed --save # 如果有安装这个的话，卸载

npm i hexo-renderer-markdown-it --save # 需要安装这个渲染插件
npm install katex @renbaoshuo/markdown-it-katex #需要安装这个katex插件

在 hexo 的根目录的 _config.yml ​中配置

1
2
3
markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'

3.13 搜索

主题支持三种搜索方式（algolia_search / local_search / docsearch），你可以选择一种或者多种搜索方式。

本地搜索

3.14 自定义字体和字体大小

可自行设置字体的font-family