Hello World, Hexo

Hexo 主页的配置和更新记录。

目录

1. Hexo 配置
2. 主题配置
3. 更新记录

Hexo 配置

从0开始环境配置

安装 Hexo 所需工具 Node.js 和 Git

Hexo 是基于 Node.js 的静态博客框架，Git 用于版本控制和部署到 GitHub Pages。

在网页上下载：

• Node.js: https://nodejs.org/en/download/
• Git: https://git-scm.com/downloads

安装后设置环境变量，确保 node 和 git 命令可用。

命令行查看版本

node -v
npm -v
git --version

本地安装 Hexo

以下命令都在 git 提供的命令行工具 Git Bash 中执行。

安装 Hexo

npm install -g hexo-cli

创建 Hexo 项目

cd path/to/your/blog
hexo init . 
npm install 
hexo g  # hexo generate 生成静态HTML文件
hexo s  # hexo server 在本地的4000端口启动服务器

访问 http://localhost:4000 查看 Hexo 默认主页。

本地连接 GitHub

在GitHub上创建Public Repository，命名为 username.github.io

1. 配置 SSH

   设置用户名和邮箱

   git config --global user.name "local_username"
   git config --global user.email "GitHub email"

   创建 SSH 密钥

   ssh-keygen -t rsa -b 4096 -C "GitHub email"

   查看 SSH 密钥

   cat ~/.ssh/id_rsa.pub

   SSH 默认路径： ~/.ssh/id_rsa.pub。格式一般为

   ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC3... user@hostname

   添加 SSH 密钥到 GitHub：Settings -> SSH and GPG keys -> New SSH key

2. 验证 SSH 连接

   ssh -T git@github.com

   连接成功，会显示Hi XXX! You've successfully authenticated, but GitHub does not provide shell access.

部署 Hexo 到 GitHub Pages

安装 Hexo 部署插件

npm install hexo-deployer-git --save

修改 `_config.yml` 配置文件

deploy:
  type: git
  repository: git@github.com:username/username.github.io.git
  branch: main/master

部署到 GitHub Pages

hexo cl # hexo clean
hexo g -d -m "commit message"

简述 Hexo 工作原理

1. Hexo 本地目录结构：

   ├── _config.yml          # global 配置文件
   ├── package.json         # Node.js 依赖配置，这个是在安装 Hexo 时生成的
   ├── node_modules         # Node.js 依赖包目录
   ├── source                # 写markdown的目录
   ├── themes                
   │   └── butterfly         # 主题目录
   │       ├── _config.yml   # 主题配置文件，这里边的选项是用来美化（魔改）网页界面外观的
   │       ├── source        # 主题静态资源目录
   │       ├── layouts       # 主题布局文件，用来魔改的
   │       ├── scripts       # 主题脚本文件，用来魔改的
   │       └── styles        # 主题样式文件，用来魔改的
   ├── scaffolds             # 模板目录
   ├── public                # 生成的静态文件目录
   └── ...                  # 其他 Hexo 生成的文件

我在这里做了一个软链接

#!/bin/bash
cd /d/home/base/blogs/Blog_CowboyCyber/source/_posts
while true; do
    find /d/home/base/blogs/Blog-Posts -type f -name "*.md" | while read file; do
        ln -sf "$file" "$(basename "$file")"
    done
    echo -e "Links created successfully at time \033[34m$(date +'%Y-%m-%d %H:%M:%S')\033[0m"
    sleep 1
done

将 _source 目录下的 md 文件链接出去，方便按照时间和主题单独管理，在 bash 中运行后每 1 秒执行一次，直到手动停止。这样能保证在单独的目录下写 Markdown 时随时更新到 Hexo 的 _source 目录下。

1. 原理

   • 什么是静态网页？

     网站上的每个页面都是一个 HTML 文件，静态网页是不需要服务器端处理，直接把预先生成的 HTML 文件发送给浏览器呈现的。在此基础上需要交互的功能则需要基于 JS 之类的脚本语言来实现。Hexo 就是在本地通过模板引擎和配置文件，将用户写的 Markdown 文件转换为 HTML 文件存入 public 目录下，然后部署到 GitHub 的仓库中。也可以不用 部署到 GitHub，而是部署到其他静态网页托管服务上（如 Vercel之类的），只要能提供静态网页托管服务即可。

   • Github 怎么把仓库里的一个个 HTML 文件组织成一个网站？

     GitHub Pages 是 GitHub 提供的静态网页托管服务，它会自动将仓库中的 index.html 文件作为主页，并将其他 HTML 文件链接起来形成一个完整的网站。

   总结：Hexo 在本地将 Markdown 文件转换为 HTML 文件，并将其存储在 public 目录下；这一目录随后通过 Git 部署到 GitHub 的仓库中，GitHub Pages 则会将这些 HTML 文件组织成一个网站。

2. Hexo 的现状

   似乎时至今日 Hexo 这个从 2013 年就开始的项目虽然社区还很活跃，但底层语言和性能已经远远落后于当前的最优实践。这里有一个锐评。不过借助大模型，将任意主题的底层移植到新的框架应该并非难事。之后如果有这样的尝试会开坑做一些记录。

主题配置

目前的主页基于 Butterfly 主题。

美化与魔改

一般来说，受开发者维护的主题对用户开放的配置选项都在 themes/your-theme/_config.yml 文件中，虽然相对有限。此外定义字体、颜色之类全局变量的还有主题的 source 目录下的 .styl 文件。

而实际上读取_config.yml 的是主题目录下种类丰富的 .css 、.js 和 .pug 后缀的文件，它们将 _config.yml 中的配置选项转换为对应的样式和功能，最终生成所有的 HTML 文件。所以在有限配置选项之外“魔改”主题样式或者加功能只需理清逻辑然后修改相应的一到两个文件即可。

我自己的魔改：主要是一键托管给 copilot …无非是些音乐外链和尽量冷酷的特效。没什么值得记录的内容。

一些 markdown 外挂标签（并不都兼容最新版本的Butterfly）

一些遇到的问题

Markdown 格式数学公式渲染问题

Butterfly 默认的前端渲染插件 hexo-renderer-marked 或 hexo-renderer-kramed 都不支持复杂的 LaTeX 公式渲染。解决方法是使用后端渲染工具 Pandoc 以及 Hexo 插件 hexo-renderer-pandoc 和 hexo-filter-mathjax。

安装后刷新环境变量，参考 前辈的文档 在 _config.yml 和 themes/butterfly/_config.yml 中配置必要参数，并进行自定义配置。

Hexo Butterfly 不支持 md 语法脚注

安装插件 hexo-footnotes，并在 _config.yml 中启用。

安装脚注插件

npm install hexo-footnotes --save

_config.yml (site)

plugins:
  - hexo-footnotes

语法：

md 语法脚注渲染效果

这是一个脚注的例子1。
[^1]: 这里是脚注内容。
这是另一个脚注的例子[^longnote]。
[^longnote]: 这里是另一个脚注内容
[^longnote]: 可以多行？

这是一个脚注的例子¹。

这是另一个脚注的例子[^longnote]。
[^longnote]: 这里是另一个脚注内容

The Bitter Lesson

现在这个时代，在大模型和 coding agent 的辅助下深入配置目录的底层魔改各种各样的样式和功能已经越来越简便，门槛前所未有地降低。但这也是更需要尊重古老箴言的时代：相较于花里胡哨的小玩意，网页里必须要有内容！

That’s also a reminder to myself: stay in balance and focused on what’s really important.

---

更新记录

2025-07 回返

😋 Retro Future with Butterfly!

换回最初的起点，而且有 copilot 陪着我~ Butterfly 充满力量和稳定性，只要读懂恰当的地方，就能引入我自己的风格。

「有一个夜晚我烧毁了所有的记忆，从此我的梦就透明了；有一个早晨我扔掉了所有的昨天，从此我的脚步就轻盈了。」

如果过去无法清算，那就带它去往明天。

新的主页目前还没有读者 😁 无问西东。

2023-10 沉沦

🥲 Wandering in the NexT Dark...

在大二上学期，又或者是大二下学期。因为厌烦了魔改不完全的花哨页面，把主题从 Butterfly 换成了 NexT。

NexT 的配置文件相对简洁，网上的教程也很多，稍微魔改一下就能满足我的审美。但移植以后对于原有的流水账内容感到过于羞耻，无论是缺章少节的课程笔记还是无病呻吟的随笔全都删掉，重新开始。

但步入大二后心境上的变化使我失去了创作和发表的欲望。接近一年的时间，在沉迷《崩坏：星穹铁道》之余只记录了选修的《社会心理学》课程笔记和《傅里叶光学导论》前几章的笔记。一年以后的大三上学期则是坚持以一周几次的频率在主页上更新日记，随着年后紧张的保研压力而中断。

这段时间里，我的「读者」只有 Jackcui 一人。

2023-03 开端

😎 The Beginning with Butterfly

在 Jackcui 的引导下初识 Hexo 🤗
当时还是连 git 都不会用的小白…在学期开始的第一节史纲课上搞定了配环境和部署一条龙。

初代主页也是因为还不太了解 Hexo 和 HTML 而改的乱七八糟的 Butterfly。因为过于年轻还坚持用电脑做课程笔记并且把主页用来连载，但随后就因为跟不上专业课的速度而逐渐放弃，等到日渐成熟后，连平板都被完全弃绝。这一年得到的只有开了个头的《离散数学》和《数据结构》，以及还算完整的《现代西方科学哲学》。同时貌似也开了一些科幻书评的坑…

这时主页的存在还有包括 Jackcui 在内的整整 2 个人知道！

---

1. 1.这里是脚注内容。 ↩