本博客采用 Hexo + GithubPage 在 Windows 平台搭建，同时使用了 Butterfly 主题。

若在搭建过程中出现问题，请善用ai/stfw/rtfm。

0. 准备

一个 github 账号，一台 Windows 设备，魔法（也许需要）。
至于为什么不用 Linux 呢，因为我懒得找 Linux 的教程，理论上应该容易一点罢。

1. 本地部署Hexo

你需要安装 Node.js 环境和 npm。推荐从官网下载。

同时，官网也有命令行安装方式，如下。若使用命令行记得不要全部直接执行，若无法执行，考虑重启命令行加载环境。

1
2
3
4
5
6
7
8
9
10
11
# Download and install fnm:
winget install Schniz.fnm

# Download and install Node.js:
fnm install 22

# Verify the Node.js version:
node -v # Should print "v22.15.1".

# Verify npm version:
npm -v # Should print "10.9.2".

然后就可以开始配置 Hexo 了，如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
# install hexo
npm install -g hexo-cli

# init hexo frame
hexo init some_dir_name
cd some_dir_name
npm install

# start hexo server
hexo s

# visit hexo server in powershell, eg. localhost:4000
# use Ctrl + Click to visit is easy!

若能打开博客网站，看到ui，则部署成功。

此时应该会有默认的一个hello world.md，你应该可以在你的网站上看到这个项目的网页。

2. 搭载主题

本博客选用的主题是 Butterfly，也可根据自己喜好选择其他主题，如NeXT等也比较常用，下文仅介绍Butterfly相关配置。

大多数配置都可以参考官方配置文档来安装，偶尔会出现插件问题，记得多问ai/stfw，本文仅作参考，只记录笔者进行了的配置内容，仅供参考。由于配置项繁多，推荐观看官方主题配置页，本文仅起辅助作用。段末给出了作者npm安装的所有包，如果出现插件问题可作参考。

以下操作若无特殊说明均在博客根目录下进行，尤其分清themes/butterfly/_config.yml和_config.yml。

2.1. 安装butterfly并配置

1
npm install hexo-theme-butterfly

打开_config.yml，修改theme项为butterfly.

1
theme: butterfly

安装其他需要的插件，如

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

进行

1
2
3
hexo clean
hexo g
hexo s

访问网页，能看到渲染成功即可。

2.2. 配置个人信息

打开_config.yml，修改下列选项，以下给出的是我的配置。

1
2
3
4
5
6
7
8
# Site
title: pi-uke's blog
subtitle: 'あっと驚くようなことの連続'
description: ''
keywords:
author: pi-uke
language: zh-CN
timezone: ''

title和subtitle显示为你的网页名，title也会显示在你的首页，author显示为你的名字。

2.3. 配置图片

打开themes/butterfly/_config.yml，修改下列选项。

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
# --------------------------------------
# Image Settings
# --------------------------------------

favicon: /img/95162603_p0-removebg-preview.png

avatar:
  img: /img/92520387_p0.jpg
  effect: false

# Disable all banner images
disable_top_img: false

# If the banner of page not setting, it will show the default_top_img
default_top_img: /img/headliner.png

# The banner image of index page
index_img: 

# The banner image of archive page
archive_img:

# Note: tag page, not tags page
tag_img:

# The banner image of tag page, you can set the banner image for each tag
# Format:
#  - tag name: xxxxx
tag_per_img:

# Note: category page, not categories page
category_img:

# The banner image of category page, you can set the banner image for each category
# Format:
#  - category name: xxxxx
category_per_img:

# The background image of footer
footer_img: /img/100734973_p0.png

# Website Background
# Can set it to color or image url
background:

cover:
  # Disable the cover or not
  index_enable: true
  aside_enable: true
  archives_enable: true
  # When cover is not set, the default cover is displayed
  default_cover:
    # - xxx.jpg

# Replace Broken Images
error_img:
  flink: /img/friend_404.gif
  post_page: /img/404.jpg

# A simple 404 page
error_404:
  enable: false
  subtitle: 'Page Not Found'
  background: /img/error-page.png

post_meta:
  # Home Page
  page:
    # Choose: created / updated / both
    date_type: created
    # Choose: date / relative
    date_format: date
    categories: true
    tags: false
    label: true
  post:
    # Choose: left / center
    position: left
    # Choose: created / updated / both
    date_type: both
    # Choose: date / relative
    date_format: date
    categories: true
    tags: true
    label: true

各个选项的含义建议看官方文档，推荐将图片放到themes\butterfly\source\img下。

2.4. 配置LaTeX

你应该能看到本文是可以流畅使用LaTeX\LaTeX的，这里使用的是KaTeX\KaTeX。

打开themes/butterfly/_config.yml，修改下列选项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# --------------------------------------
# Math
# --------------------------------------

# About the per_page
# if you set it to true, it will load mathjax/katex script in each page
# if you set it to false, it will load mathjax/katex script according to your setting (add the 'mathjax: true' or 'katex: true' in page's front-matter)
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

另外需要安装的插件

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插件

在_config.yml中添加：

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

试着在博客中添加LaTeX公式，测试行间公式∫0πsin⁡xdx\int_0^\pi\sin x\mathrm dx和公式块

∫0πsin⁡xdx[abcd]=ad−bc \int_0^\pi\sin x\mathrm dx\\ \begin{bmatrix} a&b\\ c&d \end{bmatrix}=ad-bc

观察能否成功渲染。

2.5. 配置评论区

本博客使用的是Waline，配置同样建议参考Waline官方文档。
配置themes/butterfly/_config.yml，注意这里bg尺寸不宜太大，同时强烈建议使用透明背景。

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
comments:
  # Up to two comments system, the first will be shown as default
  # Leave it empty if you don't need comments
  # Choose: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo/Giscus/Remark42/Artalk
  # Format of two comments system : Disqus,Waline
  use: waline
  # Display the comment name next to the button
  text: true
  # Lazyload: The comment system will be load when comment element enters the browser's viewport.
  # If you set it to true, the comment count will be invalid
  lazyload: false
  # Display comment count in post's top_img
  count: false
  # Display comment count in Home Page
  card_post_count: false

# ...

# Waline - A simple comment system with backend support fork from Valine
# https://waline.js.org/
waline:
  serverURL: waline-eta-ten.vercel.app
  bg:
  # Use Waline pageview count as the page view count
  pageview: true
  option:

文档写的很详细，这里仅补充个人遇到的问题。

  1. 若Vercel部署失败，建议等一段时间重试。
  2. Vercel部署完成后有三个网页地址，有的不行，如果部署到博客后出现fetch failed之类的错误就换一个，理论上是waline-****-ten.vercel.app（ten也许也是可变参数？）。

2.6. npm包列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
hexo-site@0.0.0 C:\Users\****\blog
+-- @renbaoshuo/markdown-it-katex@2.0.2
+-- hexo-deployer-git@4.0.0
+-- hexo-filter-katex@1.1.0
+-- hexo-filter-mathjax@0.9.0
+-- hexo-generator-archive@2.0.0
+-- hexo-generator-category@2.0.0
+-- hexo-generator-feed@3.0.0
+-- hexo-generator-index@3.0.0
+-- hexo-generator-searchdb@1.5.0
+-- hexo-generator-sitemap@3.0.1
+-- hexo-generator-tag@2.0.0
+-- hexo-math@5.0.0
+-- hexo-renderer-ejs@2.0.0
+-- hexo-renderer-markdown-it@7.1.1
+-- hexo-renderer-pandoc@0.5.0
+-- hexo-renderer-pug@3.0.0
+-- hexo-renderer-stylus@3.0.1
+-- hexo-server@3.0.0
+-- hexo-theme-landscape@1.1.0
+-- hexo-wordcount@6.0.1
+-- hexo@7.3.0
`-- katex@0.16.22

这里实现的是一个极为简化的版本，后续也许还会更新自己的实现，但是不会再更新这篇博客了，更建议读者自己实现。

3. 部署到GithubPage上

3.1. 创建一个GithubPage

创建项目<username>.github.io。注意在Settings/Code and automation/Pages类里面修改Source为Deploy from a branch, Branch选择master /(root)，如图。

3.2. 修改本地配置

修改_config.yml

1
2
3
4
5
6
7
8
9
10
# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://<username>.github.io

# ...

deploy:
  type: git
  repo: https://github.com/<username>/<username>.github.io.git
  branch: master

3.3. 推送到GithubPage

安装deploy-git，然后推送即可。

1
2
3
4
npm install hexo-deployer-git --save
hexo clean
hexo g
hexo d # hexo deploy

第一次推送可能需要一段时间才能访问成功。

若推送出现网络状况，可考虑更换SSH方式，配置SSH密钥后改为SSH形式，如下

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:<username>/<username>.github.io.git
  branch: master



Referfences:

  1. https://mini-pi.github.io/2024/02/28/how-to-make-blog-wedsite/
  2. https://butterfly.js.org/
  3. https://waline.js.org/