================================================================================
                          Hexo 博客项目说明文档
================================================================================

项目名称: vanishke随笔
项目描述: 基于 Hexo 框架的静态博客网站
作者: vanishke
主题: Next
网站地址: https://github.com/vanishke/hexo

================================================================================
                              环境要求
================================================================================

1. Node.js (推荐 v14.0.0 或更高版本)
2. Git
3. npm 或 yarn 包管理器

================================================================================
                              安装步骤
================================================================================

1. 克隆项目到本地
   git clone https://github.com/vanishke/hexo.git
   cd hexo

2. 安装依赖
   npm install
   或
   yarn install

3. 安装 Hexo CLI (如果尚未安装)
   npm install -g hexo-cli

================================================================================
                              项目结构
================================================================================

hexo/
├── source/              # 源文件目录
│   ├── _posts/         # 博客文章目录
│   │   └── blogs/      # 博客文章 (237篇)
│   ├── about/          # 关于页面
│   ├── archives/       # 归档页面
│   ├── categories/     # 分类页面
│   ├── tags/           # 标签页面
│   └── ...             # 其他页面
├── themes/             # 主题目录
│   └── next/           # Next 主题
├── public/             # 生成的静态文件目录
├── _config.yml         # Hexo 配置文件
├── package.json        # 项目依赖配置
└── README.txt          # 本说明文件

================================================================================
                              常用命令
================================================================================

1. 创建新文章
   hexo new "文章标题"
   或
   hexo new post "文章标题"

2. 启动本地服务器
   hexo server
   或
   hexo s
   或
   npm run server
   
   访问地址: http://localhost:4000

3. 生成静态文件
   hexo generate
   或
   hexo g
   或
   npm run build

4. 清理缓存和生成文件
   hexo clean
   或
   npm run clean

5. 部署到 GitHub
   hexo deploy
   或
   hexo d
   或
   npm run deploy

6. 一键操作 (清理 + 生成 + 启动服务器)
   使用 hexo-server.bat 脚本 (Windows)
   或手动执行:
   hexo clean && hexo g && hexo s

================================================================================
                              快速开始
================================================================================

1. 安装依赖
   npm install

2. 启动本地服务器
   npm run server
   或
   hexo server

3. 在浏览器中访问
   http://localhost:4000

4. 开始编写文章
   在 source/_posts/blogs/ 目录下创建 .md 文件

================================================================================
                              配置说明
================================================================================

主要配置文件: _config.yml

重要配置项:
- title: 网站标题 (vanishke随笔)
- subtitle: 网站副标题
- author: 作者名称 (vanishke)
- language: 语言设置 (zh-CN)
- theme: 主题名称 (next)
- url: 网站地址
- deploy: Git 部署配置

修改配置后需要重启服务器才能生效。

================================================================================
                              插件说明
================================================================================

项目使用的主要插件:

1. hexo-deployer-git          # Git 部署插件
2. hexo-generator-search       # 搜索功能
3. hexo-generator-searchdb     # 搜索数据库
4. hexo-toc                    # 目录生成
5. hexo-wordcount              # 字数统计
6. hexo-symbols-count-time     # 阅读时间统计
7. hexo-neat                   # 代码压缩
8. hexo-filter-mermaid-diagrams # Mermaid 图表支持
9. hexo-asset-image            # 图片资源处理
10. gitalk                     # 评论系统

================================================================================
                              部署说明
================================================================================

部署到 GitHub Pages:

1. 确保 _config.yml 中的 deploy 配置正确
   deploy:
     type: git
     repository: https://github.com/vanishke/hexo.git
     branch: master

2. 执行部署命令
   hexo deploy
   或
   npm run deploy

3. 部署前会自动执行 hexo generate 生成静态文件

注意: 首次部署需要配置 Git 凭据。

================================================================================
                              开发建议
================================================================================

1. 文章编写
   - 使用 Markdown 格式
   - 文章放在 source/_posts/blogs/ 目录
   - 文章头部需要包含 Front Matter (YAML格式)

2. 图片资源
   - 建议使用图床服务
   - 或使用 hexo-asset-image 插件处理本地图片

3. 主题定制
   - 主题配置文件在 themes/next/_config.yml
   - 不要直接修改主题文件，建议使用 source/_data/ 目录覆盖

4. 备份
   - 定期提交代码到 Git 仓库
   - 备份 source/ 目录和 _config.yml 文件

================================================================================
                              常见问题
================================================================================

Q: 本地服务器无法启动？
A: 检查端口 4000 是否被占用，或使用 -p 参数指定其他端口
   hexo server -p 5000

Q: 修改配置后没有生效？
A: 执行 hexo clean 清理缓存，然后重新生成和启动

Q: 部署失败？
A: 检查 Git 配置和仓库地址是否正确，确保有推送权限

Q: 文章不显示？
A: 检查文章 Front Matter 格式是否正确，date 字段是否有效

Q: 主题样式异常？
A: 检查主题是否正确安装，执行 npm install 重新安装依赖

================================================================================
                              更新日志
================================================================================

Hexo 版本: 5.2.0
Node.js 版本: 请查看 package.json

================================================================================
                              联系方式
================================================================================

GitHub: https://github.com/vanishke/hexo
博客: https://github.com/vanishke/hexo

================================================================================
                              许可证
================================================================================

本项目为个人博客项目，遵循相关开源协议。

================================================================================
                              最后更新
================================================================================

文档生成时间: 2025-01-XX
项目维护者: vanishke

================================================================================