GiHub Pages + Hexo ブログの爆誕

前言

最近终于能从忙碌中脱身，挤出点时间做自己的事情。遂重拾这搁置多年的项目，开辟一个属于自己的天地(博客)，将我所经历的时光铭刻于文字中，而不是任凭它们随记忆消散。随着年龄增长，人逐渐被卷入社会的漩涡，与越来越广阔的世界交织，独属于自己的时间被逐渐增加的琐事蚕食。我开始意识到，若非难事，真正想做的事、珍视的事情，最适时机就是当下。无论多么忙碌，我们都需要保留一份独属于自己的闲暇，仔细耕耘内心的处女地，而非任凭琐事侵染，最终只留得一事无成的感慨。

碎碎念就到此为止 ...... 简单介绍对这个博客的想法。如前面所说，我建立这个博客的初衷就是记录日常所思所得，记录和谈论与我一切感兴趣领域：动漫、音乐、文学、物理、化学相关的话题。文章形式可能包括短评、技术日志、学习笔记、(碎碎念)等。虽是这样规划的，等真正开始之后大概也不会拘于形式，随性而写吧(笑)。(总之能够坚持下去就足够了)

以下是参考Fany Full's Blog的搭建流程。

背景

简单介绍GiHub Pages + Hexo approach的背景知识。

GitHub Pages是GitHub提供的一项服务，可将托管在GitHub上一个仓库username.github.io中的html、css、js代码渲染成静态页面。每个GiHub账户只能有一个这样的仓库(仓库的可见性需设为public)。上传博客内容后，可通过域名https://www.username.github.io访问博客，这里username是自己的github用户名。使用GitHub Pages搭建博客有诸多优点，如免费方便、数据绝对安全且能恢复历史版本、可灵活设计博客外观等。

准备工作

• 注册GitHub账号
• 安装git for windows (或其他git客户端)，并进行基本配置
• 安装node.js、npm

配置Git for Windows

已经有GibHub账号，这里简单记录git for windows的配置

打开Git Bash，设置用户名和邮箱。在命令行输入

$ git config --global user.name "user_name" # user_name 填入 GitHub 用户名
$ git config --global user.email "user_email" # user_email 填入 GitHub 注册的邮箱 

配置 SSH key

ssh-keygen -t rsa -C "user.email" # user.email 为GitHub 上注册的邮箱

默认不需要设置密码。可以选择在指定的路径下产生ssh密钥：私钥id_rsa和公钥id_rsa.pub。将id_rsa.pub内容全部复制，打开GitHub_Settings_keys界面，新建new SSH key

标题任拟，将id_rsa.pub的内容复制到Key一栏，点击Add SSH key。通过ssh连接GiHub仓库需要C:\Users\username\.ssh路径下存有私钥文件id_rsa。用以下命令检测能否成功连接：

ssh -T git@github.com

参考这篇文章设置代理：

git config --global http.proxy 'http://127.0.0.1:7890'
git config --global https.proxy 'https://127.0.0.1:7890'

安装node.js

进入官网下载windows版本，安装时勾选所有组件，并将其添加到系统环境变量

检验安装

node -v
npm -v

基于Hexo框架搭建博客

官方文档： https://hexo.io/zh-cn/docs/

“Hexo 是一个快速、简洁且高效的博客框架。 Hexo 使用 Markdown（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。”

GitHub：https://github.com/hexojs/hexo

Hexo 使用 Markdown 语法解析存放在本地的文章内容，生成相应的html、css、js文件。 Github Pages 存放的都是静态文件，博客存放的不只是文章内容，还有文章列表、分类、标签、翻页等动态内容，有了Hexo就可以在更新文章后快速批量生成相关页面，再将有改动的页面提交到Github，更新博客。这样大大节省我们的精力，使我们能够集中于文章的撰写。

本文使用环境

• windows 10
• node.js version — v22.13.1
• npm ——v10.9.2
• git version —2.42.0.windows.2

安装和初始化

git bash中输入

npm install -g hexo-cli # 此命令完成对 hexo 的安装

安装完成后，在本地新建文件夹(E:)存放博客的代码。这个文件夹将用于存放博客所有内容和素材，博客所有操作都在其中完成。

进入新建博客目录，输入：

hexo init # hexo 在本地博客目录的初始化

产生以下文件夹

生成静态文件

Git bash输入以下命令：

hexo g  #生成静态文件

然后Hexo就会在public文件夹中生成相关html、js、css文件，待提交到username.github.io仓库中，渲染成网页。下面的index.html就是Hexo提供的Hellow World模板。

本地预览

hexo s #开启本地预览

通过本地预览可以实时查看博客的渲染效果。打开浏览器访问http://localhost:4000/即可查看内容，Ctrl+C停止本地预览。

上传到Github

首先安装部署插件

npm install hexo-deployer-git --save # 安装部署插件

Hexo有两种_config.yml文件，一种是根目录下的全局配置文件(站点配置文件)，另一种是各个主题下的主题配置文件。配置文件的参数可以在此处查询。我们先配置站点配置文件：

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:chem1912/chem1912.github.io.git #(graminilune)
  branch: master

在Git bash中输入以下命令，部署到Github

hexo d

打开https://username.github.io/

更改主题

以常用主题NexT为例展示如何更换主题。

官方文档 https://theme-next.iissnan.com/

克隆next主题文件夹到站点目录的themes文件夹下

git clone https://github.com/theme-next/hexo-theme-next.git themes/next

打开站点配置文件，在Extensions段设置

theme: next

切换主题之前使用hexo clean，然后hexo g，hexo s

可在NexT的主题配置文件中切换主题风格

# Schemes
scheme: Muse
#scheme: Mist
#scheme: Pisces
#scheme: Gemini

其他主题：

• fluid主题 https://fluid-dev.github.io/hexo-fluid-docs/
• ocean主题 https://github.com/zhwangart/hexo-theme-ocean?tab=readme-ov-file

渲染公式问题

Hexo渲染数学公式：配置方法与原理浅释

Hexo中数学公式渲染失败的解决

Nunjucks Errors

成功解决在hexo中无法显示数学公式的问题

采用mathjax渲染公式

需安装支持mathjax的渲染器

npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-pandoc --save

在全局配置文件加入

math:
  engine: 'mathjax'
  mathjax:
    src: custom_mathjax_source

next的主题配置文件中加入

# hexo-renderer-pandoc (or hexo-renderer-kramed) required for full MathJax support.
mathjax:
  enable: true
  # See: https://mhchem.github.io/MathJax-mhchem/
  mhchem: false
  cdn: https://cdn.jsdelivr.net/npm/mathjax@2.7.8/MathJax.js?config=TeX-AMS-MML_HTMLorMML

如果仍然渲染失败，可以尝试在md文件开头yml部分加入

mathjax: true

连续花括号问题

过于复杂的公式仍然容易解析失败：

Nunjucks Error: _posts/正则系综与恒温动力学.md [Line 13, Column 35] expected variable end

此时需要对公式格式微调。一个例子是，以下公式中两个连续的花括号会使得渲染失败：

$$
\hat H=\frac{{\bf p_i}^2}{2m_i}
$$

需在花括号之间加入空格或字符：

$$
\hat H=\frac{ {\bf p_i}^2}{2m_i}
$$

狄拉克符号问题

发现量子力学中常用的Dirac符号无法正常渲染。在Latex中书写狄拉克符号可以用：

$$ 
\langle \Psi | \Psi \rangle
$$
或
$$
\lang \Psi | \Psi \rang
$$

显示结果为 \[ \langle \Psi | \Psi \rangle \] 但mathjax似乎无法正确识别、。另一种方式需要physics宏包，采用的mathjax源默认有这个宏包，因而可行：

$$
\bra{\Psi}\ket{\Psi}
$$

显示结果为 \[ \bra{\Psi}{}\ket{\Psi} \] 如果要严谨点，这里应该用内积的形式：

$$
\ip{\Psi}{\Psi}
$$

但Hexo无法渲染。

期望值，需要这样书写：

\left<\hat O\right>

\[ \left<\hat O\right> \]

这是physics宏包的手册

公式换行问题

最初用"\\"简单分隔Latex公式各行的方式，Hexo渲染出来没有换行。简单有效的解决办法是采用对齐符，如：

\begin{align}\quad \sum_{i}p_i-1&=0\\
\sum_{i}p_i{\cal E_i}-U&=0 \\
\sum_{i}p_i{\cal N_i}-N&=0 \end{align}\tag{1.39} 

用"&"指定对齐的位置。渲染效果为 \[ \begin{align}\quad \sum_{i}p_i-1&=0\\ \sum_{i}p_i{\cal E_i}-U&=0 \\ \sum_{i}p_i{\cal N_i}-N&=0 \end{align}\tag{1.39} \] 总结来说，用markdown书写博文需要良好的编辑习惯，能传达同样内容的前提下采用最简洁方便方式呈现，公式只需展示核心的，这样能大大节省调整格式和排版的时间。

图床配置

搭建一个免费图床！彻底解决博客文章中图片存储问题！

新建GitHub仓库并生成Token

在GitHub上新建一个仓库blog_picture用于存储博客图片。

在账户全局设置处找到Developer settings，点击进入设置Token（注意需要时classic token）：

image-20250206143306923

勾选user、workflow、write:packages、admin:org。

点击Generate token即可生成token。生成的token只会在第一次显示，需要及时保存。

PicGo配置GitHub图床

PicGo是一个用于快速上传图片并获取图片URL链接的工具。可在此处下载PicGo，使用指南在这里。

安装好PicGo后可进一步配置。

首先可自定义快捷键，“Windows中快捷上传的快捷键是Ctrl+Shift+P，点击 PicoGo 左侧栏的 PicGo 设置和修改快捷键设置，可以按自己喜好修改快捷键。此外，PicGo 有快速截图并上传的功能，在插件设置中搜索 quick-capture，然后进行安装，默认的快捷键是Ctrl+Shift+0，也可以进行修改。”

另外可在设置内开启“上传前重命名”，使得在PicGo上传图片前弹出一个窗口让我们重命名图片。

设置GiHub图床：

Typora配置PicGo

点击验证图片上传选项，如下图所示则为验证成功

其他方案

hexo-asset-img | Hexo 本地图片插件: 转换 图片相对路径 为 asset_img

可以使用插件hexo-asset-image

首先安装插件

npm install hexo-asset-image --save

打开根目录下的_config.yml配置文件，将以下字段设为true

post_asset_folder: true

新建md文件时

hexo new 'blog_name' # blog_name填入文章名字

会同时创建与该文件名同名的文件夹，同时存放在source/_post/目录下。

文章的图片资源存放在该目录下，使用Markdown语法就可以链接到图片。

结语

基于GiHub Pages + Hexo + PicGo + Typora 搭建了博文写作的工作流，之后就是写作时间了。Enjoy Writing!