项目结构参考文档

本文档旨在提供对该仓库（一个基于 Jekyll 和 Minimal Mistakes 主题的个人博客网站）的全面结构分析，以便于未来的维护、开发和内容更新。

1. 技术栈概览

  • 静态网站生成器: Jekyll - 一个基于 Ruby 的简单、强大的静态网站生成器。
  • Jekyll 主题: Minimal Mistakes - 一个功能丰富且响应式的 Jekyll 主题。本仓库通过 SCSS 覆盖和数据文件配置对其进行了定制。
  • 包管理: Bundler (Gemfile) - 用于管理 Ruby gem 依赖。
  • 持续集成/持续部署 (CI/CD): GitHub Actions (.github/workflows/) - 用于在代码推送到仓库后自动构建和部署网站。

2. 核心目录结构

以下是本项目中关键目录和文件的功能说明：

/
├── _config.yml               # Primary configuration file for the entire site
├── _data/                    # Data files (navigation, UI text, etc.)
│   ├── navigation.yml        # Defines links for the top navigation bar
│   └── ui-text.yml           # Overrides the theme's UI text
├── _includes/                # Reusable HTML snippets (header, footer, etc.)
├── _layouts/                 # Templates defining the overall HTML structure of pages
│   ├── default.html          # Base layout
│   ├── home.html             # Homepage layout
│   └── single.html           # Layout for individual post pages
├── _posts/                   # Blog posts (in Markdown format)
├── _sass/                    # SCSS stylesheets. Overrides/extends Minimal Mistakes theme styles
│   └── minimal-mistakes.scss # Main file to import custom styles
├── assets/                   # Static assets
│   ├── css/                  # Compiled CSS
│   ├── images/               # Image files
│   └── js/                   # JavaScript files
├── pages/                    # Independent pages of the site (e.g., About Me, Categories)
├── .github/workflows/        # GitHub Actions workflow definitions
│   └── build.yml             # Automates the building and deployment of the Jekyll site
├── Gemfile                     # Defines Ruby dependencies
└── index.html                # Entry point for the homepage

3. 工作流程详解

a. 内容创作与管理

  • 博客文章:
    • 所有文章都位于 _posts 目录下。
    • 文件名必须遵循 Jekyll 的命名规范：YYYY-MM-DD-title.md。
    • 每篇文章的开头都包含 YAML Front Matter，用于定义文章的元数据，如布局（layout）、标题（title）、日期（date）、分类（categories）、标签（tags）等。
  • 独立页面:
    • 位于根目录下的 Markdown 文件，如 about_me.md、categories.md 和 tags.md。
    • 这些文件同样使用 Front Matter 来指定布局和标题。例如，gallery.md 使用 layout: gallery 来调用 _layouts/gallery.html 布局。

b. 配置与定制

  • 全局配置 (_config.yml):
    • 这是最重要的配置文件，定义了网站的 URL、标题、作者信息、社交链接、Markdown 渲染器、Jekyll 插件等。
    • 对此文件的修改会影响整个网站的行为和元数据。
  • 导航 (_data/navigation.yml):
    • 此文件定义了网站顶部导航栏的链接结构。通过修改此文件，可以轻松添加、删除或重排导航项。
  • 外观与样式 (_sass/):
    • 本仓库通过 _sass/minimal-mistakes.scss 文件来定制 Minimal Mistakes 主题的外观。
    • 你可以在此文件中修改主题变量（如颜色、字体大小）或添加全新的 CSS 规则，以覆盖默认样式。
  • 布局与组件 (_layouts/ 和 _includes/):
    • _layouts 目录中的 HTML 文件定义了不同类型页面的宏观结构。
    • _includes 目录存放着可在多个布局中重复使用的代码片段，如页眉、页脚、侧边栏、评论区等。如果需要对网站的某个特定部分进行结构性修改，通常会编辑此目录中的文件。

c. 资源管理

  • 图片: 存放于 assets/images/。可以在文章中通过 Markdown 语法 ![alt text](/assets/images/image.jpg) 来引用。
  • JavaScript: 自定义的 JS 代码位于 assets/js/。

4. 构建与部署

  • 本地开发:
    1. 确保已安装 Ruby 和 Bundler。
    2. 运行 bundle install 安装 Gemfile 中指定的依赖。
    3. 运行 bundle exec jekyll serve 启动本地开发服务器，默认地址为 http://127.0.0.1:4000/。
  • 自动部署:
    • .github/workflows/build.yml 文件配置了一个 GitHub Action。
    • 当有新的 commit 被推送到 master (或 main) 分支时，该 Action 会被触发。
    • 它会自动执行 Jekyll 的构建命令，并将生成的静态网站文件（位于 _site 目录）部署到 GitHub Pages。

此文档为您提供了一个清晰的路线图。当您需要进行特定更改时，可以参考上述说明来定位相关文件。