题头图

GitHub博客网站项目文件结构图

文档版本： v1.1
更新日期： 2026-04-10
项目名称： yifree.github.io

📁 项目整体结构

yifree.github.io-5/                    # 项目根目录
├── .vscode/                           # VS Code配置
├── .github/workflows/                 # GitHub Actions工作流
├── _includes/                         # Jekyll包含文件
├── _layouts/                          # Jekyll布局文件
├── _posts/                            # 文章内容
├── assets/                            # 静态资源
│   ├── css/                          # 样式文件
│   ├── images/                       # 图片资源
│   └── js/                           # JavaScript脚本
├── git-hooks/                        # Git钩子脚本
├── 项目配置文件
├── 开发文档
└── 自动化脚本

📋 详细文件说明

🔧 开发环境配置

.vscode/settings.json

  • 是否必须： ❌ 可选
  • 主要作用： VS Code编辑器配置
  • 使用条件： 使用VS Code进行开发
  • 使用方法： 自动加载，无需手动操作

☁️ GitHub Actions自动化

.github/workflows/update-toc.yml

  • 是否必须： ❌ 可选（方案三）
  • 主要作用： 自动更新文章目录的GitHub Actions工作流
  • 使用条件： GitHub仓库，配置了Actions权限
  • 使用方法：
    1. 推送包含文章变化的代码
    2. GitHub自动运行工作流
    3. 自动更新文章目录并提交

📄 Jekyll包含文件（_includes/）

_includes/gitalk.html

  • 是否必须： ❌ 可选
  • 主要作用： Gitalk评论系统集成
  • 使用条件： 需要配置GitHub OAuth应用
  • 使用方法： 自动包含在文章页面中

_includes/toc.html

  • 是否必须： ✅ 必须
  • 主要作用： 生成文章目录导航
  • 使用条件： 文章包含标题结构
  • 使用方法： 自动处理，无需手动干预

_includes/umami.html

  • 是否必须： ❌ 可选
  • 主要作用： Umami网站统计代码
  • 使用条件： 配置了Umami统计服务
  • 使用方法： 自动包含在所有页面中

🎨 Jekyll布局文件（_layouts/）

_layouts/default.html

  • 是否必须： ✅ 必须
  • 主要作用： 网站默认布局模板
  • 使用条件： 所有页面使用此布局
  • 使用方法： Jekyll自动应用

📝 文章内容（_posts/）

_posts/2024-05-20-test.md

  • 是否必须： ❌ 示例文件
  • 主要作用： 测试文章示例
  • 使用条件： 可删除或修改
  • 使用方法： Jekyll自动处理为网页

_posts/2026-04-08-笔记一.md

  • 是否必须： ❌ 示例文件
  • 主要作用： 学习笔记示例
  • 使用条件： 可删除或修改
  • 使用方法： Jekyll自动处理为网页

_posts/2026-04-08-笔记二.md

  • 是否必须： ❌ 示例文件
  • 主要作用： 学习笔记示例
  • 使用条件： 可删除或修改
  • 使用方法： Jekyll自动处理为网页

_posts/2026-04-08-笔记文档模板.md

  • 是否必须： ❌ 示例文件
  • 主要作用： 文章写作模板
  • 使用条件： 可删除或修改
  • 使用方法： 参考格式编写新文章

🎨 静态资源（assets/）

assets/css/style.css

  • 是否必须： ✅ 必须
  • 主要作用： 网站样式定义
  • 使用条件： 所有页面引用
  • 使用方法： 自动加载，可自定义修改

assets/images/avatar.jpg

  • 是否必须： ✅ 必须
  • 主要作用： 网站头像图片
  • 使用条件： 首页显示
  • 使用方法： 自动加载，可替换为个人头像

assets/images/header.jpg

  • 是否必须： ✅ 必须
  • 主要作用： 网站题头图
  • 使用条件： 所有页面顶部显示
  • 使用方法： 自动加载，可替换为个人图片

assets/js/script.js

  • 是否必须： ✅ 必须
  • 主要作用： 网站交互功能
  • 使用条件： 所有页面引用
  • 使用方法： 自动加载，包含搜索、暗黑模式等功能

🔄 Git自动化脚本（git-hooks/）

git-hooks/pre-commit

  • 是否必须： ❌ 可选（方案二）
  • 主要作用： Git提交前自动更新文章目录
  • 使用条件： 已安装Git钩子
  • 使用方法： 通过setup-git-hooks.py安装

⚙️ 项目配置文件

_config.yml

  • 是否必须： ✅ 必须
  • 主要作用： Jekyll网站配置
  • 使用条件： 部署前需要个性化配置
  • 使用方法： 修改网站标题、描述、URL等信息

404.md

  • 是否必须： ✅ 必须
  • 主要作用： 404错误页面
  • 使用条件： 访问不存在的页面时显示
  • 使用方法： Jekyll自动处理

archive.md

  • 是否必须： ✅ 必须
  • 主要作用： 文章归档页面
  • 使用条件： 需要归档功能
  • 使用方法： 访问/archive.html查看

feed.xml

  • 是否必须： ✅ 必须
  • 主要作用： RSS订阅源
  • 使用条件： 支持RSS阅读器
  • 使用方法： 订阅/feed.xml获取更新

feed.xsl

  • 是否必须： ✅ 必须
  • 主要作用： RSS样式表，美化RSS feed页面
  • 使用条件： 浏览器中查看RSS feed时
  • 使用方法： 自动应用，无需手动操作

index.md

  • 是否必须： ✅ 必须
  • 主要作用： 网站首页
  • 使用条件： 访问根目录时显示
  • 使用方法： Jekyll自动处理

search.json

  • 是否必须： ✅ 必须
  • 主要作用： 搜索功能数据源
  • 使用条件： 需要搜索功能
  • 使用方法： JavaScript自动调用

tags.md

  • 是否必须： ✅ 必须
  • 主要作用： 标签分类页面
  • 使用条件： 需要标签功能
  • 使用方法： 访问/tags.html查看

📚 开发文档

README.md

  • 是否必须： ✅ 必须
  • 主要作用： 项目说明文档
  • 使用条件： GitHub仓库首页显示
  • 使用方法： 阅读了解项目信息

文章目录.md

  • 是否必须： ✅ 必须
  • 主要作用： 静态文章目录（GitHub显示）
  • 使用条件： 在GitHub上浏览文章列表
  • 使用方法： 通过脚本自动生成

建议报告.md

  • 是否必须： ❌ 可选
  • 主要作用： 项目优化建议
  • 使用条件： 项目改进参考
  • 使用方法： 阅读了解改进方向

20260408Github博客网站项目开发工作记录.md

  • 是否必须： ❌ 可选
  • 主要作用： 历史开发记录
  • 使用条件： 了解项目开发历程
  • 使用方法： 阅读了解开发过程

20260409Github博客网站项目开发工作记录.md

  • 是否必须： ❌ 可选
  • 主要作用： 当前开发记录
  • 使用条件： 了解最新开发进展
  • 使用方法： 阅读了解最新进展

20260409Github博客网站项目综合建议报告.md

  • 是否必须： ❌ 可选
  • 主要作用： 项目综合分析和建议
  • 使用条件： 项目改进参考
  • 使用方法： 阅读了解完整分析

README_文章目录生成器.md

  • 是否必须： ✅ 必须
  • 主要作用： 文章目录生成器使用说明
  • 使用条件： 使用自动化脚本时参考
  • 使用方法： 阅读了解三种更新方案

项目文件结构图.md

  • 是否必须： ✅ 必须
  • 主要作用： 项目文件结构说明（本文档）
  • 使用条件： 了解项目文件组织
  • 使用方法： 阅读了解文件作用

🤖 自动化脚本

generate_toc.py

  • 是否必须： ✅ 必须
  • 主要作用： 文章目录自动生成主脚本
  • 使用条件： 需要Python环境
  • 使用方法： python generate_toc.py

setup-git-hooks.py

  • 是否必须： ❌ 可选（方案二）
  • 主要作用： Git钩子安装脚本
  • 使用条件： 需要Git环境
  • 使用方法： python setup-git-hooks.py install

🔧 开发工具文件

4_20260408_yifree.github.io.code-workspace

  • 是否必须： ❌ 可选
  • 主要作用： VS Code工作区配置
  • 使用条件： 使用VS Code进行开发
  • 使用方法： 用VS Code打开此文件

📊 文件分类统计

按重要性分类

  • 必须文件： 16个（核心功能）
  • 可选文件： 11个（增强功能）
  • 示例文件： 4个（参考学习）

按功能分类

  • Jekyll核心： 8个文件
  • 静态资源： 4个文件
  • 自动化脚本： 3个文件
  • 开发文档： 8个文件
  • 配置工具： 8个文件

🚀 部署前检查清单

必须修改的文件

  1. _config.yml - 修改网站基本信息
  2. 文章目录.md中的链接 - 修改为个人域名
  3. 图片文件 - 替换为个人头像和题头图

可选配置的文件

  1. Gitalk评论系统 - 配置OAuth应用
  2. Umami统计 - 配置统计服务
  3. 自动化方案 - 选择适合的更新方案

测试验证

  1. 本地运行Jekyll测试
  2. 部署到GitHub Pages
  3. 验证所有功能正常

💡 使用建议

新手用户

  1. 先修改_config.yml基本配置
  2. 使用方案一（手动运行脚本）
  3. 逐步学习其他功能

开发者用户

  1. 配置方案二（Git钩子）实现自动化
  2. 自定义样式和功能
  3. 考虑部署方案三（GitHub Actions）

团队项目

  1. 统一使用方案三（GitHub Actions）
  2. 建立代码审查流程
  3. 定期备份重要数据

文档维护： 此文档应随项目更新而维护
最后更新： 2026-04-09
维护人员： 项目开发者