博客搭建基础教程(三)

前言

参考：Hexo博客搭建基础教程(三)，Butterfly 安裝文檔(三) 主題頁面，Butterfly 安裝文檔(四) 主題配置-2 | Butterfly
参考或者直接搬运他们的教程，方便收藏，不怕某天作者的博客突然挂了导致无法参考🙈🙈🙈
Fomalhaut大佬在B站有搭建视频，而且博客进行了开源，可以去大力支持一波👍
全程我将会和大家一起进行搭建，大家可以放心食用。

博客搭建与魔改系列教程导航🚥🚥🚥

前言

博客搭建过程遇到任何问题，优先在本页面搜索，检查是否已经有该配置教程。
无法解决问题可以阅读Fomalhaut的博客或者官方搭建教程寻求解决方案。
你也可以在文章评论区留言，注意留言时请填写正确的邮箱以确保能收到站长的回复。

语言

修改站点配置文件_config.yml，默认语言是 en 。支持三种语言

default（英语）
zh-CN（简体中文）
zh-TW（繁体中文）

网站资料

修改网站各种资料，例如标题、副标题和邮箱等个人资料，请修改站点配置文件_config.yml。部分参数如下，详细参数可参考官方的配置描述。

参数	描述
title	网站标题
subtitle	描述
description	网站描述
keywords	网站的关键词。支持多个关键词
author	您的名字
language	网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 zh-Hans和 zh-CN。
timezone	网站时区。Hexo 默认使用您电脑的时区。请参考时区列表进行设置，如 America/New_York, Japan, 和 UTC 。一般的，对于中国大陆地区可以使用 Asia/Shanghai

导航菜单

修改主题配置文件_config.butterfly.yml

必须是 /xxx/，后面||分开，然后写图标名，如果不想显示图标，图标名可不写
可以直接在子目录里添加 hide 隐藏子目录，如下面的List

menu:
  Home: / || fas fa-home
  Archives: /archives/ || fas fa-archive
  Tags: /tags/ || fas fa-tags
  Categories: /categories/ || fas fa-folder-open
  List||fas fa-list||hide:
   Music: /music/ || fas fa-music
    Movie: /movies/ || fas fa-video
  Link: /link/ || fas fa-link
  About: /about/ || fas fa-heart

文字可自行更改，中英文都可以

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

代码

1 代码高亮主题

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

darker
pale night
light
ocean
mac
mac light

修改主题配置文件_config.butterfly.yml中的highlight_theme属性。

1	highlight_theme: darker

2 代码复制

修改主题配置文件_config.butterfly.yml中的highlight_copy属性，true表示可以复制。

1	highlight_copy: true

3 代码框展开/关闭

修改主题配置文件_config.butterfly.yml中的highlight_shrink属性。

1	highlight_shrink: true #代码框不展开，需点击 '>' 打开

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

true 全部代码框不展开，需点击>打开
false 代码框展开，有>点击按钮
none 不显示>按钮

4 代码换行

在默认情况下，Hexo 在编译的时候不会实现代码自动换行。如果你不希望在代码块的区域里有横向滚动条的话，那么你可以考虑开启这个功能。
修改主题配置文件_config.butterfly.yml中的code_word_wrap属性。

1	code_word_wrap: true

5 代码高度限制

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

修改主题配置文件_config.butterfly.yml中的highlight_height_limit属性。

1	highlight_height_limit: false # unit: px

单位是px，直接添加数字，如 200
实际限制高度为highlight_height_limit + 30 px ，多增加 30px 限制，目的是避免代码高度只超出highlight_height_limit 一点时，出现展开按钮，展开没内容。
不适用于隐藏后的代码块（ css 设置 display: none）。

社交图标

Butterfly支持font-awesome v6图标。
书写格式：图标名：url || 描述性文字 || 颜色。

1
2
3

social:
  fab fa-github: https://github.com/xxxxx || Github || '#24292e'
  fas fa-envelope: mailto:xxxxxx@gmail.com || Email || '#4a7dbe'

顶部图

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

配置	解释
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

修改主题配置文件_config.butterfly.yml

1	index_img: xxx.png

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

文章置顶与封面

你可以直接在文章的front-matter区域里添加sticky: 1属性来把这篇文章置顶。数值越大，置顶的优先级越大。

文章的markdown文档上，在Front-matter添加cover，并填上要显示的图片地址。如果不配置cover，可以设置显示默认的cover；如果不想在首页显示cover，可以设置为false。
修改主题配置文件_config.butterfly.yml。

cover:
  index_enable: true      # 是否显示文章封面
  aside_enable: true      # 侧栏是否显示文章封面图
  archives_enable: true   # 归档页面是否显示文章封面图
  position: both          # 封面显示的位置 left/right/both
  # 当没有设置cover时，默认的封面显示
  default_cover:

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

default_cover:
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg.png
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg2.png
  - https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg3.png

文章页相关配置

1 文章meta显示

post_meta这个属性用于显示文章的相关信息的，修改主题配置文件_config.butterfly.yml。

post_meta:
  page:
    date_type: both # created or updated or both 主页文章日期是创建日或者更新日或都显示
    date_format: relative # date/relative 显示日期还是相对日期
    categories: true # true or false 主页是否显示分类
    tags: true # true or false 主页是否显示标签
    label: true # true or false 显示描述性文字
  post:
    date_type: both # created or updated or both 文章页日期是创建日或者更新日或都显示
    date_format: relative # date/relative 显示日期还是相对日期
    categories: true # true or false 文章页是否显示分类
    tags: true # true or false 文章页是否显示标签
    label: true # true or false 显示描述性文字

2 文章版权和协议许可

修改主题配置文件_config.butterfly.yml

post_copyright:
  enable: true
  decode: false
  author_href:
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

由于Hexo 4.1开始，默认对网址进行解码，以至于如果是中文网址，会被解码，可设置decode: true来显示中文网址。如果有文章（例如：转载文章）不需要显示版权，可以在文章页Front-matter中单独设置。

1	copyright: false

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

post_copyright:
copyright_author: xxxx
copyright_author_href: https://xxxxxx.com
copyright_url: https://xxxxxx.com
copyright_info: 此文章版权归xxxxx所有，如有转载，请註明来自原作者

3 文章打赏

修改主题配置文件_config.butterfly.yml

reward:
  enable: false
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: wechat
    - img: /img/alipay.jpg
      link:
      text: alipay

4 文章目录TOC

toc:
  post: true            # 文章页是否显示 TOC
  page: false           # 普通页面是否显示 TOC
  number: true          # 是否显示章节数
  expand: false         # 是否展开 TOC
  style_simple: true    # 简洁模式（侧边栏只显示 TOC, 只对文章页有效 ）
  scroll_percent: true  # 是否显示滚动进度百分比

5 相关文章推荐

相关文章推荐的原理是根据文章tags的比重来推荐，修改主题配置文件_config.butterfly.yml。

# 相关文章推荐
related_post:
  enable: true        # 是否显示推荐文件
  limit: 6            # 显示推荐文章数目
  date_type: created  # or created or updated 文章日期显示创建日或者更新日

6 文章锚点

开启文章锚点后，当你在文章页进行滚动时，文章链接会根据标题ID进行替换。

注意: 每替换一次，会留下一个歷史记录。所以如果一篇文章有很多锚点的话，网页的歷史记录会很多。

修改主题配置文件_config.butterfly.yml。

1
2
3

anchor:
  auto_update: false         # 当您滚动时，URL将根据标头id进行更新
  click_to_scroll: false     # 单击标题滚动并更新锚点

7 文章过期提醒

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

# 文章过期提醒
# 可设置是否显示文章过期提醒，以更新时间为基准。
noticeOutdate:
  enable: false
  style: flat       # style: simple/flat
  limit_day: 500    # 距离更新时间多少天才显示文章过期提醒
  position: top     # 显示在文章的位置: top/bottom
  # 天数之前的文字
  message_prev: 距离上次更新已经过去了 
  # 天數之後的文字
  message_next:  天，文章的内容可能已经过时了。

8 文章分页按钮

修改主题配置文件_config.butterfly.yml

1 2	# post_pagination (分页) post_pagination: false

设置参数：

false:为关闭分页按钮
1:下一篇显示的是旧文章
2:下一篇显示的是新文章

头像

修改主题配置文件_config.butterfly.yml

1
2
3

avatar:
  img: /assets/head.jpg
  effect: false # true则会一直转圈

文章内容复制相关配置

修改主题配置文件_config.butterfly.yml

copy:
  enable: true        # 是否开启网站复制权限
  copyright:          # 复制的内容后面加上版权信息
    enable: true      # 是否开启复制版权信息添加
    limit_count: 50    # 字数限制，当复制文字大于这个字数限制时，将在复制的内容后面加上版权信息

修改主题配置文件_config.butterfly.yml

footer:
  owner:
    enable: true
    since: 2022		# 站点起始时间
  custom_text:		# 是一个给你用来在页脚自定义文本的选项。通常你可以在这里写声明文本等,支持 HTML。
  copyright: false 	 # Copyright of theme and framework

可以参考tzy大佬的的custom_text填写示例：

custom_text: I wish you to become your own sun, no need to rely on who's light.<p><a target="_blank" href="https://hexo.io/"><img src="https://img.shields.io/badge/Frame-Hexo-blue?style=flat&logo=hexo" title="博客框架为Hexo"></a>&nbsp;<a target="_blank" href="https://butterfly.js.org/"><img src="https://img.shields.io/badge/Theme-Butterfly-6513df?style=flat&logo=bitdefender" title="主题采用butterfly"></a>&nbsp;<a target="_blank" href="https://www.jsdelivr.com/"><img src="https://img.shields.io/badge/CDN-jsDelivr-orange?style=flat&logo=jsDelivr" title="本站使用JsDelivr为静态资源提供CDN加速"></a> &nbsp;<a target="_blank" href="https://vercel.com/ "><img src="https://img.shields.io/badge/Hosted-Vervel-brightgreen?style=flat&logo=Vercel" title="本站采用双线部署，默认线路托管于Vercel"></a>&nbsp;<a target="_blank" href="https://vercel.com/ "><img src="https://img.shields.io/badge/Hosted-Coding-0cedbe?style=flat&logo=Codio" title="本站采用双线部署，联通线路托管于Coding"></a>&nbsp;<a target="_blank" href="https://github.com/"><img src="https://img.shields.io/badge/Source-Github-d021d6?style=flat&logo=GitHub" title="本站项目由Gtihub托管"></a>&nbsp;<a target="_blank" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img src="https://img.shields.io/badge/Copyright-BY--NC--SA%204.0-d42328?style=flat&logo=Claris" title="本站采用知识共享署名-非商业性使用-相同方式共享4.0国际许可协议进行许可"></a></p>

效果展示

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

1	custom_text: <a href="icp链接"><img class="icp-icon" src="icp图片"><span>备案号：xxxxxx</span></a>

右下角按钮

1 简繁转换

修改主题配置文件_config.butterfly.yml

translate:
  enable: false
  default: 繁                   # 默认按钮显示文字(网站是简体，应设置为'default: 繁')
  defaultEncoding: 2            # 网站默认语言，1: 繁体中文, 2: 简体中文
  translateDelay: 0             # 延迟时间,若不在前, 要设定延迟翻译时间, 如100表示100ms,默认为0
  msgToTraditionalChinese: '繁' # 当文字是简体时，按钮显示的文字
  msgToSimplifiedChinese: '簡'  # 当文字是繁体时，按钮显示的文字

2 夜间模式

修改主题配置文件_config.butterfly.yml

darkmode:
  enable: true
  button: true      # dark 和 light 两种模式切换按钮
  autoChangeMode: 2	# 自动切换功能
  # 设置明亮模式时间. 数值在 0-24 之间. 如果不设置时间，默认时间是 6 和 18
  start: 6
  end: 20

autoChangeMode，可开启自动切换light mode 和 dark mode。

autoChangeMode: 1 跟随系统而变化，不支持的浏览器/系统将按照时间晚上6点到早上6点之间切换为 dark mode。
autoChangeMode: 2只按照时间点到点之间为 light mode,其余时间为dark mode。
autoChangeMode: false 取消自动切换。

3 阅读模式

阅读模式下会去掉除文章外的内容，避免干扰阅读。只会出现在文章页面，右下角会有阅读模式按钮。

修改主题配置文件_config.butterfly.yml

1	readmode: true

侧边栏设置

1 排版

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

修改主题配置文件_config.butterfly.yml，下面是本人博客的配置项可以参考

aside:
  enable: true              # 是否启用侧边栏
  hide: false               # 是否隐藏
  button: true              # 是否显示你隐藏按钮
  mobile: true              # 是否在手机上展示
  position: right           # left or right 显示在左侧或者右侧
  display:
    archive: false
    tag: true
    category: true
  card_author:              # 信息卡片
    enable: true
    description:
    button:
      enable: true          # 信息页面按钮是否展示
      icon: # fab fa-github # 按钮上的ICON
      text: 前往小窝         # 文字描述
      link: https://github.com/Le0der
  card_announcement:        # 公告栏
    enable: true
    content:
  card_recent_post:         
    enable: false
    limit: 5 # if set 0 will show all
    sort: date # date or updated
    sort_order: # Don't modify the setting unless you know how it works
  card_categories:          # 分类
    enable: false
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
    sort_order: # Don't modify the setting unless you know how it works
  card_tags:                 # 标签 
    enable: false
    limit: 40 # if set 0 will show all
    color: false
    orderby: random # Order of tags, random/name/length
    order: 1 # Sort of order. 1, asc for ascending; -1, desc for descending
    sort_order: # Don't modify the setting unless you know how it works
  card_archives:            # 归档
    enable: false
    type: monthly # yearly or monthly
    format: MMMM YYYY # eg: YYYY年MM月
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending
    limit: 8 # if set 0 will show all
    sort_order: # Don't modify the setting unless you know how it works
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order: # Don't modify the setting unless you know how it works
  card_post_series:
    enable: true
    series_title: false # The title shows the series name
    orderBy: 'date' # Order by title or date
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending

2 访问人数(UV 和 PV)

修改主题配置文件_config.butterfly.yml

busuanzi:
  site_uv: true # 本站总访客数
  site_pv: true # 本站总访问量 
  page_pv: true # 本文总阅读量

3 运行时间

修改主题配置文件_config.butterfly.yml

# 网页开通时间
# 配置格式: Month/Day/Year Time or Year/Month/Day Time
runtimeshow:
  enable: false
  publish_date: 1/1/2024 00:00:00

4 最新评论

如果未配置任何评论，前先不要开启该功能。

最新评论只会在刷新时才会去读取，并不会实时变化。
由于 API 有访问次数限制，为了避免调用太多，主题默认存取期限为 10 分鐘。也就是説，调用后资料会存在 localStorage 里，10分鐘内刷新网站只会去 localStorage 读取资料。 10 分鐘期限一过，刷新页面时才会去调取 API 读取新的数据。

修改主题配置文件_config.butterfly.yml

newest_comments:
  enable: false # 是否开启功能
  sort_order:   # 不要修改设置, 除非已经研究明白了工作原理
  limit: 6      # 显示的数量
  storage: 10   # 设置缓存时间，单位 分钟 
  avatar: true  # 是否显示头像

网站背景

修改主题配置文件_config.butterfly.yml

# 图片格式 url(http://xxxxxx.com/xxx.jpg)
# 颜色（HEX值/RGB值/颜色单词/渐变色)
# 留空 不显示背景
background: url(http://xxxxxx.com/xxx.jpg)

如果你的网站根目录不是'/'，使用本地图片时，需加上你的根目录。
例如：网站是 https://yoursite.com/blog，引用一张img/xx.png图片，则设置background为 url(/blog/img/xx.png)

自定义字体和字体大小

1 全局字体

修改主题配置文件_config.butterfly.yml中的font-family属性即可，如不需要配置，请留空。

font:
  global-font-size: '15px'
  code-font-size: '14px'
  font-family: -apple-system, Microsoft Yahei, 'PingFang SC', 'Quicksand', 'Nimbus Roman No9 L', 'Hiragino Sans GB', 'Noto Serif SC', 'WenQuanYi Micro Hei', 'ST Heiti', sans-serif;
  code-font-family: Consolas, 'Microsoft YaHei', Menlo, "PingFang SC", "Microsoft JhengHei", sans-serif

2 Blog 标题字体

修改主题配置文件_config.butterfly.yml中的blog_title_font属性即可，如不需要配置，请留空。
如不需要使用网络字体，只需要把font_link留空就行。

blog_title_font:
  font_link:
  font-family: Yunmobei, "Microsoft YaHei", -apple-system, "Segoe UI", "Helvetica Neue", Lato, Roboto, "PingFang SC", "Microsoft JhengHei",  sans-serif

网站副标题

可设置主页中显示的网站副标题或者喜欢的座右铭。

修改主题配置文件_config.butterfly.yml中的subtitle

subtitle:
  enable: false
  effect: true # 打字效果
  # Customize typed.js (配置typed.js)
  # https://github.com/mattboldt/typed.js/#customization
  typed_option: 
  # source 调用第三方服务
  # source: false 关闭调用
  # source: 1  调用一言网的一句话（简体） https://hitokoto.cn/
  # source: 2  调用一句网（简体） http://yijuzhan.com/
  # source: 3  调用今日诗词（简体） https://www.jinrishici.com/
  source: 3
   # 如果关闭打字效果，subtitle 只会显示 sub 的第一行文字
  sub:
    - 今日事&#44;今日毕

页面加载动画preloader

当进入网页时，因为加载速度的问题，可能会导致top_img图片出现断层显示，或者网页加载不全而出现等待时间，开启preloader后，会显示加载动画，等页面加载完，加载动画会消失。

# 加载动画
preloader:
  enable: true  # 是否开启  
  source: 1     # 1. 全屏加载 / 2. 部分加载 (通过进度条)
  pace_css_url: # 部分加载主题 (see https://codebyzach.github.io/pace/)

字数统计

注意必须要安装依赖才能设置为true，否则会报错！

安装插件：在你的博客根目录，打开cmd命令窗口执行npm install hexo-wordcount --save。

开启配置：修改主题配置文件_config.butterfly.yml中的wordcount。

wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

参考butterfly官方文档，查看配置教程

图片大图查看模式

fancybox和medium-zoom两个大图查看模式只能开启一个，个人推荐使用fancybox，修改主题配置文件_config.butterfly.yml。

1	fancybox: true

如果你并不想为某张图片添加大图查看模式，你可以使用 html 格式引用图片，并为图片添加 no-lightbox class 名，例如：<img src="xxxx.jpg" class="no-lightbox">。

Pjax

当用户点击链接，通过 ajax 更新页面需要变化的部分，然后使用 HTML5 的 pushState 修改浏览器的 URL 地址。这样可以不用重复加载相同的资源（css/js），从而提升网页的加载速度。

pjax: 
  enable: true
  # 对于一些第三方插件，有些并不支持 pjax 。
  # 你可以把网页加入到 exclude 里，这个网页会被 pjax 排除在外。
  # 点击该网页会重新加载网站。
  exclude: 
    - /music/
    - /no-pjax/

注意：使用 pjax 后，一些自己DIY的js可能会无效，跳转页面时需要重新调用（例如朋友圈、说说等），具体请参考Pjax文档。

Inject

如想添加额外的 js/css/meta 等等东西，可以在 Inject 里添加，head(</body>标签之前)， bottom(</html>标签之前)。

inject:
  head:
    - <link rel="stylesheet" href="/xxx.css">
  bottom:
    - <script src="xxxx"></script>

这是之后添加自定义功能会频繁使用的一个配置项。

前言

语言

网站资料

导航菜单

代码

1 代码高亮主题

2 代码复制

3 代码框展开/关闭

4 代码换行

5 代码高度限制

社交图标

顶部图

文章置顶与封面

文章页相关配置

1 文章meta显示

2 文章版权和协议许可

3 文章打赏

4 文章目录TOC

5 相关文章推荐

6 文章锚点

7 文章过期提醒

8 文章分页按钮

头像

文章内容复制相关配置

Footer 设置

右下角按钮

1 简繁转换

2 夜间模式

3 阅读模式

侧边栏设置

1 排版

2 访问人数(UV 和 PV)

3 运行时间

4 最新评论

网站背景

自定义字体和字体大小

1 全局字体

2 Blog 标题字体

网站副标题

页面加载动画preloader

字数统计

图片大图查看模式

Pjax

Inject