Tobyty's Personal Blog —— 一个基于 Jekyll 的个人博客
- Ruby 3.4.4
- Jekyll 4.4.1
- 主题 jekyll-theme-mammut（自定义 fork）
TYNote/
├── _posts/ # 已发布的博客文章（Markdown 格式）
├── _drafts/ # 草稿目录（按年份分目录管理）
├── _config.yml # Jekyll 配置文件
├── _data/ # 数据文件（联系方式等）
├── _includes/ # 模板片段
├── _tabs/ # 导航标签页
├── assets/ # 静态资源
│ ├── img/ # 图片
│ │ ├── avatar/ # 头像
│ │ ├── favicons/# 网站图标
│ │ └── posts/ # 文章图片
│ └── lib/ # 第三方库（不要修改）
├── .github/ # GitHub 配置
│ └── workflows/ # CI/CD 工作流
├── Gemfile # Ruby 依赖
└── index.html # 首页
# 安装 Ruby（使用 rbenv）
brew install rbenv
rbenv install 3.4.4
# 安装依赖
bundle install当主题仓库 jekyll-theme-mammut 有更新时：
bundle update jekyll-theme-mammutbundle exec jekyll serve
# 访问 http://127.0.0.1:4000bundle exec jekyll build
# 输出到 _site/ 目录在 _posts/ 目录创建文件，命名格式：YYYY-MM-DD-标题.md
文件开头需要 Front Matter：
---
title: 文章标题
date: YYYY-MM-DD
categories: [分类]
tags: [标签]
---草稿存放在 _drafts/ 目录，按年份分子目录管理。
master(源码) --push/PR--> GitHub Actions 构建 --> gh-pages(产物) --> pages-build-deployment --> Pages 站点
- 修改源码 → 合并到
master - 触发 Action「Build and Deploy Jekyll Site」自动构建
- 构建产物写入
gh-pages分支 - 平台自动执行
pages-build-deployment发布到 GitHub Pages
| 分支 | 作用 | 生命周期 |
|---|---|---|
master |
唯一源码分支，存放稳定可发布的代码 | 长期（主干分支，永久存在） |
develop |
开发分支，可存放脏提交/半成品，作为日常开发的临时工作区 | 长期（持续存在，但内容可随时重写） |
gh-pages |
构建产物分支，仅存放 _site/ 静态站点文件 |
短期（每次部署都强制重建：CI 用 force_orphan: true 创建孤儿提交，旧历史被覆盖，分支只保留最近一次构建结果） |
gh-pages 生命周期说明：由于
force_orphan: true，每次自动部署都会丢弃该分支全部历史、以全新孤儿提交重建。因此它不是一个累积历史的分支，本质上是"当前站点快照"，短生命周期、随时可弃。禁止手动推送——手动内容会被下次构建覆盖，且会被保护规则拦截。
master：要求 PR 审查，禁止直接 pushgh-pages：要求 PR 审查；force push 例外仅授予github-actions[bot]，保证自动部署不被拦截
- 改代码：新建分支 → 修改 → push → 创建 PR → 合并到
master（自动触发部署） - 发布站点：无需任何手动操作，合并 PR 即自动完成
- 禁止：
git push origin gh-pages（会被保护规则拒绝，且下次构建会覆盖手动内容）
develop(开发) --push--> 创建 PR --> 合并到 master --> 自动构建 --> gh-pages --> 自动发布
- 在
develop分支上开发、提交、推送 - 在 GitHub 上创建
develop → master的 Pull Request - 通过审查后合并（走 master 的 PR 保护规则）
- 合并即触发「Build and Deploy Jekyll Site」→ 自动部署到 gh-pages → 站点更新
本项目使用自定义主题 jekyll-theme-mammut，引用 release 分支。
jekyll-theme-mammut (主题仓库) TYNote (博客仓库)
│ │
│ 修改主题样式/布局 │ 撰写文章/配置
│ │
▼ ▼
推送到 release 分支 ──────────▶ bundle install 拉取最新主题
│ │
│ ▼
│ 本地预览 / CI 构建
│ │
└──────────────────────────────▶ 部署到 blog.tobyty.wang
定义网站顶部导航栏的页面，每个文件对应一个标签页：
| 文件 | 说明 | Front Matter |
|---|---|---|
about.md |
关于页面 | icon: fas fa-info-circle, order: 4 |
archives.md |
归档页面 | order: 1 |
categories.md |
分类页面 | order: 2 |
tags.md |
标签页面 | order: 3 |
icon- Font Awesome 图标类名order- 导航栏显示顺序（数字越小越靠前）
存放 YAML 格式的数据文件，供模板调用：
_data/
├── contact.yml # 社交联系方式配置
└── origin/
└── basic.yml # 静态资源路径配置
contact.yml - 配置侧边栏显示的社交链接：
type- 平台类型（github、email、cnblogs 等）icon- 图标类名（Font Awesome 或自定义 iconfont）noblank- 是否在当前标签页打开链接
origin/basic.yml - 配置前端库的 CSS/JS 路径：
- 字体：webfonts、iconfont
- 功能库：tocbot（目录）、mermaid（图表）、MathJax（数学公式）等
存放可复用的 HTML 模板片段，用于覆盖或扩展主题默认模板：
| 文件 | 说明 |
|---|---|
head.html |
HTML <head> 部分，包含 SEO 标签、资源引用、分析代码等 |
sidebar.html |
侧边栏模板，包含头像、站点标题、导航菜单、社交链接 |
这些文件会覆盖主题中的同名模板，实现自定义布局。
当主题仓库有更新时，在博客项目执行：
bundle update jekyll-theme-mammut- 样式/布局修改 → 在 jekyll-theme-mammut 仓库进行
- 文章/配置修改 → 在本仓库进行
- 主题修改推送到
release分支后，博客项目需更新依赖
_site/目录由 CI 自动生成，不要提交到 Gitassets/lib/是第三方库，不要修改- 修改
.ruby-version时需同步更新 GitHub Actions 配置 - 日常只需操作
develop，master与gh-pages均无需手动干预。 - 说明：
deploy.yml监听master分支的 push，因此无论直接推master还是通过 PR 合并，都会触发相同的自动构建流程。 - develop 生命周期补充：
develop可随时 force reset 或删除重建，不影响部署与master（CI 只监听 master，develop 的任何操作都不触发构建）。