📚 文档目录

🚀 butterfly主题(一)安装部署 - 📌 butterfly主题(二)基本设置 - 🌈 butterfly主题(三)美化

butterfly 是 Hexo 静态网站框架的一个主题，简洁美观自由度高，非常适合爱折腾的站长。

环境

安装

安装 Hexo

  1. Windows 首次安装需启用 windows shell 外部脚本权限，以管理员权限执行执行以下命令，Y 回车确认
1
Set-ExecutionPolicy -ExecutionPolicy Bypass
  1. npm更换国内镜像源
1
npm config set registry https://registry.npmmirror.com/
  1. 安装 hexo 初始化脚本
1
npm install -g hexo-cli
  1. 创建并进入 hexo 目录，作为博客目录
1
mkdir hexo && cd hexo
  1. 初始化(安装 Hexo)
1
hexo init
项目初始结构（版本不同可能有细微差异）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.
├── .github
| 	└── dependabot.yml  # 依赖更新脚本，会创建一个新分支存放最新依赖，建议删除
├── node_modules # 依赖
├── scaffolds # 模板，可在这里设置 Front Matter
| 	├── draft.md  # 草稿模板
| 	├── page.md # 页面模板
|	  └── post.md # 文章模板
├── source # 存放文章、页面
|	  └── _posts  # 文章
├── themes  # 主题文件目录
├── _config.landscape.yml # 默认主题配置，安装完新主题后可删除
├── _config.yml # 站点配置文件
├── .gitignore  # git忽略文件，用来指定哪些文件或者目录不被提交
├── package.json  # 包管理配置文件，记录项目信息和依赖名称及版本
└── package-lock.json # 存储每个安装的依赖是哪个版本

安装 butterfly

  1. 下载主题
1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
  1. 删除themes\butterfly\.git、themes\butterfly\.github目录
1
Remove-Item -LiteralPath "themes\butterfly\.git", "themes\butterfly\.github" -Recurse -Force
  1. 安装 pug 以及 stylus 的渲染器（不安装主题无法显示）
1
npm install hexo-renderer-pug hexo-renderer-stylus --save
  1. 应用主題，修改 hexo 配置文件_config.yml，搜索theme:字段，修改默认主题为butterfly
1
theme: butterfly

常用命令

Hexo基本命令 作用
hexo init 一键安装Hexo
hexo s 本地运行博客，默认端口4000
hexo clean 清除静态资源
hexo g 编译为HTML代码，默认目录public
hexo n title 创建一篇新的文章，文章标题是 title

内容创建

Front Matter

文章和页面的相关参数设置

页面 Front Matter

1
2
3
4
5
6
7
8
9
10
11
12
---
title:  # 页面标题
type: # 标签、分类和友情链接三个页面需要配置
top_img:  # 页面顶部图片
comments: # 显示页面评论模块（默认 true）
aside:  # 显示侧边栏（默认 true）

description:  # 页面描述
keywords: # 页面关键词

aplayer:  # 在需要的页面加载aplayer的js和css
---

文章 Front Matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
title: 笔记 # 文章标题
categories: 前端 # 文章分类
tags: CSS # 文章标签
date: 2022-01-12 11:51:53 # 文章创建日期
keywords: # 文章关键词
description:  # 文章描述，设置后优先出现在文章预览界面

top_img:  # 文章顶部图片
cover:  # 文章封面（如果没有设置top_img，文章页顶部将显示缩略图，可设为false/图片地址/留空）

sticky: 1 # 文章置顶，数值越大，优先级越大
comments: # 【可选】显示文章评论模块（默认 true）
mathjax:  # 【可选】显示mathjax（当设置mathjax的per_page： false时，才需要配置，默认 false）
katex:  # 【可选】显示katex（当设置katex的per_page： false时，才需要配置，默认 false）
---

文章多分类写法

1
2
3
4
5
6
7
8
# 两个单独分类
categories: 
  - 笔记,linux

# 子分类写法，"linux"是"笔记"的一个子分类
categories: 
  - 笔记
  - linux

创建页面

分类页面

1
hexo new page categories

创建完成后在 Front Matter 添加

1
2
3
4
type: "categories"
top_img: false
aside: false
comments: false

标签页面

1
hexo new page tags

创建完成后在 Front Matter 添加

1
2
3
4
type: "tags"
top_img: false
aside: false
comments: false

关于页面

1
hexo new page about

创建完成后在 Front Matter 添加

1
2
3
4
type: "about"
top_img: false
aside: false
comments: false

友链页面

1
hexo new page link

创建完成后在 Front Matter 添加

1
2
3
type: "link"
top_img: false
aside: false

在source/_data目录中（如果沒有_data文件夹，请自行创建），创建一个文件link.yml，编辑你的友链

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
- class_name: 友链一组
  class_desc: 友链一组描述
  link_list:
    - name: 博客园
      link: https://www.cnblogs.com/
      avatar: https://www.cnblogs.com/favicon.ico
      descr: 开发者的网上家园

- class_name: 友链二组
  class_desc: 友链二组描述
  link_list:
    - name: 阿里云
      link: https://www.aliyun.com/
      avatar: https://img.alicdn.com/tfs/TB1_ZXuNcfpK1RjSZFOXXa6nFXa-32-32.ico
      descr: 为了无法计算的价值
    - name: 腾讯云
      link: https://cloud.tencent.com/
      avatar: https://cloud.tencent.com/favicon.ico
      descr: 产业智变·云启未来

说说页面

1
hexo new page shuoshuo

创建完成后在 Front Matter 添加

1
2
3
type: "shuoshuo"
top_img: false
aside: false

数据来源

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

author和avatar可省略，会自动去获取配置文件中的author和avatar
如果需要开啓评论，必须配置key，否则不会显示评论按钮

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
- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-21 23:33:26
  key: key-1
  content: |
    This is a sample content for **Author 1**.
    ![Sample Image](https://via.placeholder.com/150)
  tags:
    - tags1
    - tags2
- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-20 23:33:26
  key: key-2
  content: |
    This is a sample content for **Author 2**.
    ![Sample Image](https://via.placeholder.com/150)
  tags:
    - tag2
    - tag3

- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-19 23:33:26
  key: key-3
  content: |
    This is a sample content for **Author 3**.

注意： 选择远程加载后，本地生成的方法会无效。
远程拉取只支持json

在说说页面 Markdown 里的 front-matter 添加远程链接 
1
shuoshuo_url: xxxxx
Json 的格式：

author和avatar可省略，会自动去获取配置文件中的author和avatar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-21 23:33:26",
    "content": "This is a sample content for **Author 1**.",
    "key": "key-1",
    "tags": ["tags1", "tags2"]
  },
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-20 23:33:26",
    "content": "This is a sample content for **Author 2**.",
    "key": "key-2",
    "tags": ["tag2", "tag3"]
  },
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-19 23:33:26",
    "content": "This is a sample content for **Author 3**."
  }
]
参数 解释
author 【可选】作者名称
avatar 【可选】作者头像
date 【必需】日期
content 【必需】内容（ Markdown 格式或者 Html 格式）
key 【可选】评论的唯一标识, 开启评论必须配置
tag 【可选】标签

创建文章

创建新文章

1
hexo new 新文章

创建后会在source/_post文件夹生成一个新文章.md文件，内容如下

1
2
3
4
5
---
title: 新文章
date: 2022-04-10 07:31:09
tags:
---

升级

在 hexo-theme-butterfly/releases 查看新版的更新内容，根据实际情况更新你的配置内容。

代码托管

将代码上传到代码托管平台，为博客部署做准备。

代码托管平台选择：
世界上最大的代码托管平台是Github，但DNS被污染在国内很难用，退而求其次选择国际版Gitlab，国内的Gitee作为备份

  1. SSH 协议配置（连接本地和远程仓库，ssh 协议无需重复输入账号密码，详细教程 | Gitee）
1
2
3
4
5
6
7
8
9
10
11
12
# 生成公钥和私钥 (按回车 3 下)
ssh-keygen -t ed25519 -C "SSH Key"

# 查看生成的 SSH 公钥和私钥
ls ~/.ssh/

# 读取公钥文件 ~/.ssh/id_ed25519.pub，将公钥添加到 gitlab、gitee
cat ~/.ssh/id_ed25519.pub

# 验证是否成功
ssh -T git@gitlab.com
ssh -T git@gitee.com
  1. 全局身份信息配置
1
2
git config --global user.name '你的名字'
git config --global user.email '你的邮箱'
  1. 初始化本地仓库并完成首次提交
1
2
3
git init -b main
git add .
git commit -m "初始化"
  1. 建立本地仓库与远程仓库的跟踪关系
1
2
3
4
5
6
7
8
# 给 origin 添加 Gitlab仓库
git remote add origin git@gitlab.com:xiaoxiudog/hexo.git

# 给 origin 追加 Gitee仓库，实现双仓库
git remote set-url --add origin git@gitee.com:xdogtop/hexo.git

# 首次推送并建立本地分支与远程分支origin的跟踪关系
git push -f --set-upstream origin main
  1. 新建shell脚本push.ps1，写入以下命令，执行./push.ps1即可一键推送代码到两个仓库
1
2
3
4
5
6
7
8
# 将项目所有文件都添加到仓库
git add .

# 备注提交时间
git commit -m "$(date)"

# 推送代码
git push

ICP备案(可选)

国内云产品使用带域名的 HTTP/HTTPS 服务或使用80,443端口时，需确保域名完成备案才能正常使用。不备案只能使用非中国大陆节点服务器提供的服务，延迟高还容易被长城防火墙阻断。

只能在云服务提供商申请备案（腾讯云、阿里云、华为云等）

以腾讯云ICP备案为例

  1. 准备一个一年以上可备案的域名

  2. 获取备案资格（一台3个月以上腾讯云服务器或一个30天以上腾讯云备案授权码）

  3. 在 腾讯云ICP备案 提交申请，1~2个工作日腾讯云会进行初审

  4. 腾讯云初审通过后会收到工信部的验证码，在ICP/IP地址/域名信息备案管理系统进行短信核验

  5. 等待管局审核通过即可，大概1~20个工作日

腾讯云备案后续流程

  • 根域名站点实际解析IP地址归属必须是腾讯云。（定期检查，不使用腾讯云会收到整改通知，不整改会被取消备案）
    • 使用腾讯云EO免费版部署根域名网站：最优解，可以做到0成本，但腾讯云EO免费版仅可通过活动获取。
    • 租用腾讯云服务器搭建根域名网站：每年花费几十到几百。
    • 将根域名直接解析到腾讯云官网的IP，使用子域名建站：邪修方法，无法悬挂备案号。
  • 根域名网页底部需要添加服务备案号和跳转至工信部。（这个很少检查，最好是做）

部署

对于中国大陆个人博客用户，没有备案的推荐使用Vercel 免费版部署，备案后推荐使用腾讯云EO免费版 Pages部署。

  • Vercel 免费版：国外的网页托管平台，免备案。

    • 流量：100G/月
    • 带宽：
    • 最大单个文件：
    • 中国大陆平均访问延迟：80ms

  • 腾讯云EO免费版 Pages：免费版仅可通过活动获取，需备案。

    • 流量：不限
    • 带宽：不限
    • 最大单个文件：25MB
    • 中国大陆平均访问延迟：40ms