第一篇博客

2026-04-14 read the source issue

用 GitHub Issues + GitHub Actions 搭建个人博客教程

参考仓库：yihong0618/gitblog 核心思路：用 GitHub Issues 写文章，用 GitHub Actions 自动将 Issues 汇总生成 README，并可选部署为静态网站。

一、原理概述

你写 Issue（博客文章）
      ↓
GitHub Actions 自动触发
      ↓
Python 脚本读取所有 Issues，按 Label 分类
      ↓
生成 README.md（博客目录）+ BACKUP/ 目录（每篇文章的 .md 备份）+ feed.xml（RSS）
      ↓
（可选）用 isite + zola 构建静态网站，部署到 GitHub Pages

整个系统零服务器费用，内容托管在 GitHub，写作即发布。

二、快速开始（5 步完成）

第 1 步：Fork 或复制仓库结构

打开 https://github.com/yihong0618/gitblog
点击右上角 Fork，fork 到你自己的账号
把新仓库重命名为 gitblog（或任意名字，后面保持一致即可）

或者：新建一个空仓库，手动复制以下关键文件：

main.py

requirements.txt

.github/workflows/generate_readme.yml

.github/workflows/generate_site.yml（可选，用于部署静态网站）

config.toml（可选，用于静态网站样式配置）

新建 BACKUP/ 空目录（可放一个 .gitkeep 文件）

第 2 步：生成 GitHub Personal Access Token

GitHub Actions 需要一个有权限的 Token 来读取 Issues 并提交 README。

登录 GitHub → 右上角头像 → Settings
左侧导航最底部 → Developer settings
Personal access tokens → Tokens (classic) → Generate new token
勾选权限：
- repo（完整仓库权限，必选）
点击 Generate token，立即复制保存（只显示一次！）

第 3 步：将 Token 添加为仓库 Secret

进入你的 gitblog 仓库页面
Settings → Secrets and variables → Actions → New repository secret
Name 填写：G_T（必须和 workflow 文件里的 ${{ secrets.G_T }} 一致）
Value 粘贴刚才复制的 Token
点击 Add secret

第 4 步：创建 Issues 标签（Labels）分类文章

GitHub Issues 的 Label 就是文章的分类目录。建议创建以下标签：

标签名	用途说明
`Top`	置顶文章（显示在 README 最上方）
`TODO`	待办清单（支持 `- [ ]` 格式）
`Friends`	友情链接（特殊格式，见下文）
`日记`	日记类文章
`技术文章`	技术博客
`生活`	生活随感
`读书笔记`	读书心得
...	按你的需求自由创建

创建方法：仓库页 → Issues → Labels → New label

注意：Top、TODO、Friends、About、Things 是特殊保留标签，不会按普通分类展示，而是有专门的处理逻辑。

第 5 步：写第一篇博客文章

进入你的仓库 → Issues → New issue
填写标题（即文章标题）
正文支持完整 Markdown 语法
右侧 Labels 选择分类标签（如 日记、技术文章）
点击 Submit new issue

提交后，GitHub Actions 会自动触发，约 1 分钟内更新 README.md。

三、工作流详解

generate_readme.yml（核心流程）

on:
  issues:
    types: [opened, edited]        # 新建或编辑 Issue 时触发
  issue_comment:
    types: [created, edited]       # 评论时触发
  push:
    branches: [master]
    paths: [main.py]               # 修改 main.py 时触发

触发后执行：

安装 Python 依赖（PyGithub、feedgen、marko、markdown）
运行 python main.py <TOKEN> <仓库名> --issue_number <issue编号>
自动 commit 并 push 更新的 README.md 和 BACKUP/*.md

main.py 做了什么

读取所有 Issues
  ├── 有 Friends 标签 → 生成友情链接表格
  ├── 有 Top 标签    → 生成置顶文章列表
  ├── 最新 5 篇      → 生成"最近更新"
  ├── 按 Label 分组  → 生成各分类目录（超过5篇折叠显示）
  ├── 有 TODO 标签   → 生成 TODO 列表（解析 - [ ] 语法）
  └── 所有 Issue 内容 → 备份为 BACKUP/<编号>_<标题>.md
                     → 生成 feed.xml（RSS订阅）

四、README.md 效果示例

自动生成的 README 结构如下：

## [Gitblog](你的博客链接)

## [友情链接](...)
（折叠显示，来自 Friends 标签 Issue 的评论）

## 置顶文章
- [文章标题](Issue链接)--2024-01-01

## 最近更新
- [最新文章](Issue链接)--2024-03-18

## 技术文章
- [文章A](...)--2024-01-01
- ...（超过5篇后折叠）

## 日记
- [文章B](...)--2024-01-01

## TODO
TODO list from [我的计划](...)--3 jobs to do--2 jobs done
- [x] 已完成事项
- [ ] 未完成事项

五、个性化配置

修改 README 头部信息

编辑 main.py 第 12-17 行的 MD_HEAD 变量：

MD_HEAD = """## [你的博客名](你的博客地址)
你的博客简介
[RSS Feed](https://raw.githubusercontent.com/{repo_name}/master/feed.xml)
"""

调整置顶/分类标签名

在 main.py 开头修改：

TOP_ISSUES_LABELS = ["Top"]       # 置顶标签
TODO_ISSUES_LABELS = ["TODO"]     # TODO标签
FRIENDS_LABELS = ["Friends"]      # 友链标签
IGNORE_LABELS = (...)             # 不参与普通分类的标签
ANCHOR_NUMBER = 5                 # 每个分类折叠前显示的文章数

友情链接格式

在 Friends 标签的 Issue 下评论（格式固定）：

名字：朋友昵称
链接：https://friend.blog.com
描述：一句话描述

然后对这条评论点 ❤️ heart，脚本会识别你 heart 过的评论并加入友链表格。

六、（可选）部署为静态网站

如果想要一个更美观的博客界面，可以启用 generate_site.yml：

修改 `generate_site.yml` 中的 BASE_URL

env:
  BASE_URL: https://你的用户名.github.io/gitblog
  # 或者使用自定义域名：
  # BASE_URL: https://blog.yourdomain.com

修改 `config.toml`

base_url = "https://你的用户名.github.io/gitblog/"

[extra]
even_title = "你的博客名"
even_menu = [
    {url = "$BASE_URL", name = "Home"},
    {url = "$BASE_URL/tags/top/", name = "置顶"},
    # 删除原作者的 About/Things 链接，改成你自己的 Issue 编号
]

开启 GitHub Pages

仓库 → Settings → Pages
Source 选择 GitHub Actions
保存后，下次触发 workflow 会自动部署

七、日常写作流程

打开 GitHub → Issues → New issue
           ↓
  写标题 + 正文（Markdown）
           ↓
  选择 Label（分类）
           ↓
  Submit new issue
           ↓
  等待约 1 分钟
           ↓
  README 自动更新 ✓
  BACKUP/ 自动备份 ✓
  feed.xml 自动更新 ✓
  静态网站自动部署 ✓（如果开启）

编辑已有文章

直接编辑对应的 Issue 正文，保存后 Actions 自动重新生成。

置顶文章

给 Issue 添加 Top 标签即可出现在置顶区域。

写 TODO 清单

创建一个带 TODO 标签的 Issue，正文用标准 Markdown 清单格式：

## 我的学习计划

- [x] 已学完 Python 基础
- [ ] 学习 Docker
- [ ] 学习 Kubernetes

完成某项后，把 - [ ] 改为 - [x]，README 自动更新进度。

八、常见问题

Q: Actions 没有自动触发怎么办？

检查 G_T Secret 是否正确设置
进入 Actions 页面手动触发（workflow_dispatch）
检查 Actions 是否被禁用（Settings → Actions → Allow all actions）

Q: 自己是仓库 owner，但 Actions 没运行？

workflow 有条件：github.repository_owner_id == github.event.issue.user.id
确保提交 Issue 的账号就是仓库拥有者

Q: 想要 RSS 订阅地址？

https://raw.githubusercontent.com/你的用户名/gitblog/master/feed.xml

Q: 能用手机写博客吗？

完全可以！GitHub 手机 App 支持创建和编辑 Issues

Q: 文章内容支持图片吗？

支持！在 Issue 编辑器里直接粘贴或拖拽图片，GitHub 自动上传并生成链接

九、仓库结构说明

gitblog/
├── .github/
│   └── workflows/
│       ├── generate_readme.yml   # Issues → README 自动化
│       └── generate_site.yml     # 部署静态网站（可选）
├── BACKUP/                       # 每篇文章的 .md 备份（自动生成）
├── main.py                       # 核心脚本
├── requirements.txt              # Python 依赖
├── config.toml                   # 静态网站配置（可选）
├── feed.xml                      # RSS 订阅文件（自动生成）
└── README.md                     # 博客首页/目录（自动生成）

十、与传统博客平台对比

特性	gitblog	Hexo/Hugo	微信公众号/知乎
写作入口	GitHub Issues	本地编辑器	平台编辑器
部署	全自动	需手动构建	平台托管
版本管理	Git 天然支持	Git	无
数据所有权	完全属于你	完全属于你	平台
评论	GitHub Issues 评论	需第三方插件	平台评论
搜索引擎收录	较难（需配置）	容易	容易
费用	免费	免费（需托管）	免费

这套方案最大的优点是极简：不需要本地环境、不需要部署服务器，只要有 GitHub 账号就能开始写作。文章永久保存在 GitHub，即使项目停止维护，内容也不会丢失。