README

1. 项目基础架构

  • Hexo 版本: 7.3.0
  • 当前主题: Cactus (已进行核心逻辑定制)
  • 源码仓库 (Source): YanCORANV/Blog_Source
    • 包含所有 Hexo 原始配置、Markdown 文章、定制化的 Cactus 主题
    • 开发环境: 所有的 hexo g, hexo s 均在此环境下运行
  • 发布仓库 (Public): YanCORANV/YanCORANV.github.io
    • 最终展示给用户的静态站点。由源码仓库通过 hexo-deployer-git 自动推送到此仓库的 main 分支
  • 开发环境: Windows 11 / WSL 2 / VS Code

Hexo 双仓库同步工作流 (Workflow)

仓库名称 属性 作用 存放内容
Blog_Source 私有 (Private) 源码备份 .md 原文、主题配置、Python 脚本、站点设置
YanCORANV.github.io 公开 (Public) 网页托管 只有生成的 HTML, CSS, JS 静态文件

自动化部署逻辑 (hexo d)

当运行 hexo d 时，发生的操作流程如下：

  1. 本地渲染 (hexo g): Hexo 引擎读取 source/_posts 下的 Markdown，结合 themes/cactus 的模板，在本地生成 public/ 目录
  2. 同步镜像: Hexo 将 public/ 目录的内容拷贝到本地隐藏文件夹 .deploy_git 中
  3. Git 推送: hexo-deployer-git 插件自动在 .deploy_git 文件夹内执行 git add, commit 和 push
  4. 目标指向: 推送的目标是 _config.yml 中定义的 repo 地址（即 .github.io 仓库）
  5. 站点上线: GitHub Pages 检测到 .github.io 仓库的代码更新，自动刷新网页

日常维护流程

  1. 部署到网站 (面向读者)
1
hexo clean && hexo g && hexo d
  • 结果: 博客网址内容更新。
  • 涉及仓库: 本地数据 -> YanCORANV.github.io。
  1. 备份源代码 (面向开发/AI)
1
2
3
git add .
git commit -m "update sources"
git push
  • 结果: .md 原稿和脚本同步到云端，防止数据丢失。
  • 涉及仓库: 本地数据 -> Blog_Source。

2. 核心依赖与插件说明

插件名称 用途 备注
hexo-deployer-git 自动化部署至 GitHub 将 public 目录推送到展示仓库
hexo-renderer-markdown-it Markdown 渲染引擎 替代默认渲染器，提供更强的插件扩展性
markdown-it-task-lists 支持任务列表 (TODO) 配合 markdown-it 实现 [ ] 语法
markdown-it-katex LaTeX 数学公式渲染 服务器端渲染，解决 SMPL/机器人等学术公式需求
hexo-generator-index 首页生成器 用于展示首页文章列表
hexo-generator-search 全文搜索索引 生成 search.xml 供主题搜索功能调用
hexo-wordcount 字数统计与阅读时长 提供每篇文章的字数及预计阅读时间
hexo-server 本地预览服务器 提供 hexo s 调试功能

3. 主题逻辑

本项目修改了 Cactus 主题的默认行为，后续维护需注意：

首页置顶逻辑

  • 修改 themes/cactus/layout/index.ejs
  • 实现方式: 将 site.posts 转换为原生 JS 数组，并使用 sort() 函数对 sticky 字段进行显式排序
  • 操作要求: 在文章 Front-matter 中添加 sticky: [数字]（数字越大越靠前）

4. 目录结构规范

1
2
3
4
5
6
7
.
├── _config.yml              # 站点全局配置文件
├── package.json             # 依赖管理
├── source/
│   └── _posts/             # 所有文章原件 (.md)
└── themes/
    └── cactus/             # 主题目录

5. 常用开发命令

  • 清理并生成: hexo clean && hexo g
  • 本地预览: hexo s (访问 http://localhost:4000)
  • 一键部署: hexo d (自动推送到发布仓库)
  • 新建文章: hexo new post "Title"

本项目通过 sync_publish.py 脚本实现多源同步与自动化部署：

  1. 多源扫描: 自动监控并提取以下 Vault 中的笔记：
    • AAAY2S2 (学期笔记)
    • Research (科研文档)
    • Blog (博客原稿)
  2. 分拣逻辑: 仅同步 YAML 中包含 display: true 的 Markdown 文件
  3. 自动路由:
    • 根据 categories 字段自动分发至 source/_posts/{category}
    • 自动创建不存在的分类文件夹
  4. 资源重定向:
    • 将 Obsidian 的 ![[]] 语法重写为标准 Markdown 路径
    • 图片统一提取并存储至 source/img/
  5. 部署与备份: 自动执行 hexo d 部署网页，并同步备份源码至本仓库

在桌面双击 PublishBlog.bat 即可一键完成：

  • 同步 Obsidian 笔记 -> 修正图片路径 -> Hexo 渲染部署 -> Git 源码备份

6. 其他配置细节

  • 数学公式: 遇到渲染问题优先检查 markdown-it 与 katex 的冲突
  • 排序权重: 首页默认先按 sticky 倒序，sticky 相同时按 date 倒序

补充

  • 给 AI 使用的Prompt