「Blog」搭建个人博客与笔记站全流程记录

这篇文章记录一下我搭建个人主页、博客和笔记站的完整过程，方便以后复盘，也可以给想搭站的朋友一个参考。

架构设计

我的整体架构参考了 TonyCrane 的实现方式，采用三站分离：

• 主页：flytomoonmh.github.io —— 纯 HTML 的 landing page，用于展示个人简介和导航
• 博客：flytomoonmh.github.io/blog/ —— Hexo + Icarus 主题，用于写技术文章和随笔
• 笔记：flytomoonmh.github.io/my-notes/ —— MkDocs Material，用于整理学习笔记和工具文档

技术选型

主页

主页采用了最轻量的方案：纯 HTML + Bootstrap 4 + 自定义 CSS。参考 TonyCrane 的 tonycrane.cc，实现了：

• 居中的头像 + 名称布局
• 一排社交图标链接（GitHub、小宇宙、Notebook、Blog、Email）
• Bootstrap Tooltip 提示
• 暗色/亮色模式切换（saveToLocal 2 天过期机制）
• JetBrains Mono + LXGW 文楷字体

博客

博客使用 Hexo 静态站点生成器，主题选用 Icarus，原因如下：

• Icarus 主题 和 TonyCrane 博客同款，界面简洁现代
• Bulma CSS 框架，响应式布局良好
• 内置搜索、代码高亮、暗色模式、PJAX 无刷新加载
• 丰富的 widget 系统（Profile、归档、分类、标签等）

部署时需要注意 root: /blog/ 的配置，因为博客部署在 GitHub Pages 的子路径下。

笔记站

笔记站使用 MkDocs + Material for MkDocs，这套组合非常适合构建结构化的知识库：

• Material 主题美观，支持暗色模式
• 内置搜索、代码高亮、标签、目录导航
• 通过 mkdocs.yml 配置导航结构非常直观
• 支持多种 Markdown 扩展（admonition、tabbed、emoji 等）

部署流程

GitHub Pages 设置

三个站点分别对应三个 GitHub 仓库：

站点	仓库	Pages 来源
主页	FlyToMoonMH.github.io	main 分支根目录
博客	FlyToMoonMH/blog	main 分支根目录
笔记	FlyToMoonMH/my-notes	GitHub Actions 自动部署

Hexo 博客部署

cd ~/Documents/GitHub/blog
hexo new "文章标题"
# 编辑 source/_posts/文章标题.md
hexo deploy

hexo deploy 会自动生成静态文件并通过 hexo-deployer-git 推送到 FlyToMoonMH/blog 仓库。

MkDocs 笔记部署

笔记站使用 GitHub Actions 自动部署。每次 push 到 main 分支后，Actions 会自动执行 mkdocs build 并部署到 GitHub Pages。

踩坑记录

1. GitHub Pages 子路径问题

博客部署在 github.io/blog/ 子路径下，Hexo 的 _config.yml 中必须设置 root: /blog/，否则所有 CSS、JS、文章链接都会 404。

2. 域名拼写错误

最初主站链接写成了 flytoonmh（少了一个 m），导致从主站点击所有子站链接都 404。这种低级错误一定要仔细检查。

3. Icarus 主题配置验证

Icarus 6.x 有严格的配置 schema 验证。如果 comment、share、donates 等插件配置格式不正确，主题会抛出警告但继续运行。建议不要留空配置，直接注释掉整个段落。

4. 广告和订阅组件

Icarus 默认开启了 Google AdSense、FeedBurner、Follow.it 等 widgets，如果不去掉，页面上会显示红色的错误提示框，非常影响美观。

后续计划

• 迁移以前写的笔记到博客中
• 配置评论系统（Giscus）
• 添加站点访问统计
• 优化暗色模式的配色细节
• 写更多技术文章填满博客

参考链接

• TonyCrane 的主页
• TonyCrane 的博客
• Hexo 官方文档
• Icarus 主题文档
• Material for MkDocs