Skip to content

Commit aaed467

Browse files
YangHanqingclaude
YangHanqing
and
claude
committed
Rewrite TinyBlog as an Astro + Preact static site (v2)
Replace the jQuery/editor.md front end with Astro content collections (build-time date sorting, no more GitHub API guesswork), a Preact GitHub-Issues comment widget using a personal access token (the old Basic Auth login no longer works since GitHub retired password-based API auth), git-remote-based zero-config owner/repo detection, and a GitHub Actions workflow that builds and deploys to GitHub Pages on push. README rewritten bilingually (EN/中文). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
1 parent 9891900 commit aaed467

50 files changed

Lines changed: 8310 additions & 1700 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.0.1",
3+
"configurations": [
4+
{
5+
"name": "tinyblog-dev",
6+
"runtimeExecutable": "npm",
7+
"runtimeArgs": ["run", "dev", "--", "--port", "4321"],
8+
"port": 4321
9+
}
10+
]
11+
}

‎.github/workflows/deploy.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [master, main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0 # keep full history so `git remote` / commit dates resolve correctly
24+
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 20
28+
cache: npm
29+
30+
- run: npm ci
31+
- run: npm run build
32+
33+
- uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: ./dist
36+
37+
deploy:
38+
needs: build
39+
runs-on: ubuntu-latest
40+
environment:
41+
name: github-pages
42+
url: ${{ steps.deployment.outputs.page_url }}
43+
steps:
44+
- id: deployment
45+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
11

2+
### Node / Astro ###
3+
node_modules/
4+
dist/
5+
.astro/
6+
.env
7+
.env.*
8+
!.env.example
9+
210
# Created by https://www.gitignore.io/api/macos
311

412
### macOS ###

‎About Me.md‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎README.md‎

Lines changed: 152 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,167 @@
1-
## TinyBlog有什么特性
2-
1. 完全静态,以至于没有任何生成程序
3-
2. 支持Markdown常用语法
4-
3. 支持Github用户添加评论
1+
# TinyBlog
52

6-
## 为什么要写 TinyBlog
7-
有时候只想简单的写一篇文章,WordPress毫无疑问过于臃肿,Jekyll需要安装,而我想要一种更简单的更新博客方式,受到开源项目[Simple](https://github.com/isnowfy/simple)的启发,我用几个晚上的时间写了一个极简的静态博客.
3+
A zero-config static blog: write Markdown, `git push`, done. Comments are
4+
"borrowed" from GitHub Issues — no database, no third-party widget, no
5+
backend of any kind.
86

9-
每次写文章只有一个步骤,push写好的md文章到`./blog`目录下, that's all .
7+
**[English](#english)** · **[中文](#中文)**
108

11-
## TinyBlog 教程
12-
1. 从[TinyBlog的Github主页](https://github.com/YangHanqing/tinyblog)fork一份到你的仓库,更改项目名称为`your_name.github.io`,几分钟后Github会自动为你开通[your_name.github.io](yanghanqing.github.io)的个人主页
9+
---
1310

14-
2. 修改`about me.md`文件作为你的个人介绍,为了更快的加载速度,也可以选择写死在`index.html`中
11+
## English
1512

16-
3. 写好markdown文件后,保存到`./blog`目录下,依次执行下面的语句即可.如果你不熟悉Git如何使用,请参考Github提供的相关教程.
13+
### Features
1714

18-
> git add .
19-
> git commit -m "Update blog"
20-
> git push
21-
22-
4. 如果修改了CNAME,记得core.js中把`user`改为自己的账户名,否则通过URL自动获取.
15+
- **Truly static** — built with [Astro](https://astro.build), deployed as
16+
plain HTML/CSS/JS to GitHub Pages.
17+
- **Write in Markdown** — drop a file in `src/content/blog/`, it appears on
18+
the site, sorted by its `date` frontmatter (no GitHub API needed to know
19+
publish order — Astro resolves it at build time).
20+
- **Comments via GitHub Issues** — each post gets its own Issue on your repo;
21+
readers comment with a personal access token, nothing touches a server you
22+
run.
23+
- **Zero config to fork** — owner/repo is auto-detected from `git remote` at
24+
build time (`src/lib/repo.ts`). Fork it, push, and it just works.
25+
- **Light/dark mode**, responsive layout, no render-blocking JS beyond the
26+
comment widget.
2327

24-
5. 分享文章给他人,可以通过在链接后加如下参数 `?title=文章名`
28+
### Quickstart
2529

26-
6. 建议新文章发布后,评论栏留空,并点击一下提交评论按钮,这样会用你自己的账户创建issue,以后如果comment有更新,不会打扰到第一个评论的人.
30+
1. Fork this repo and rename it to `<your-github-username>.github.io`.
31+
2. In the repo Settings → Pages, set the source to **GitHub Actions**
32+
(the included workflow at `.github/workflows/deploy.yml` handles the rest).
33+
3. Edit `src/site.config.ts` — title, bio, social links. That's the only
34+
file you need to touch; owner/repo isn't in there because it's detected
35+
automatically.
36+
4. Write a post:
37+
```
38+
src/content/blog/my-first-post.md
39+
```
40+
```yaml
41+
---
42+
title: "My First Post"
43+
date: 2026-07-04
44+
description: "One line for the post list."
45+
---
46+
Hello, world.
47+
```
48+
5. `git push`. GitHub Actions builds and deploys automatically —
49+
`https://<your-username>.github.io` is live within a minute or two.
2750

28-
## 迭代方向
29-
* 修复未知Bug(没有做测试,也没有考虑Github通讯不佳的情况)
30-
* 支持响应式布局(第一次写前端,很手生)
31-
* 基本上整个网站有交互就有AJAX,所以需要美化和增加相应的Loading提示
32-
* 支持文章按发布时间排序(Github没有获取单独文件update时间的api,所有第一版没有处理,初步想法是通过 `001#TITLE`这样的命名规范来处理文章顺序)
33-
* 做一个支持MD语法的Chrome扩展来更新博客,不过如果做了扩展,和Jekyll也没什么区别了,再议.
34-
* 改成 ReactJS 驱动来练练手
51+
Local dev: `npm install && npm run dev`.
52+
53+
### How comments work
54+
55+
GitHub removed password-based API auth entirely, so Basic Auth with a
56+
username+password is no longer possible. This uses a **classic personal
57+
access token** instead:
58+
59+
1. A commenter clicks "Generate one" in the comment box, which opens GitHub's
60+
token page pre-scoped to `public_repo`.
61+
2. The token is pasted into the page and kept only in that tab's
62+
`sessionStorage` — it's sent straight to `api.github.com` from the
63+
browser and never touches any server of yours.
64+
3. On first comment, the site opens an Issue titled `[TinyBlog] <post-slug>`;
65+
every comment after that (from anyone) posts to the same Issue.
66+
67+
**Security note:** a classic PAT with `public_repo` scope can open issues/PRs
68+
on *any* public repo you have access to, not just this one — that's a GitHub
69+
limitation (classic tokens aren't repo-scoped). Anyone commenting should use
70+
a token dedicated to this purpose and revoke it afterward, or create a
71+
fine-grained token restricted to just this repository with only the
72+
"Issues: read and write" permission.
73+
74+
Reading comments is unauthenticated and public (GitHub's anonymous API rate
75+
limit is 60 requests/hour per IP) — fine for a personal blog's traffic.
76+
77+
### Project layout
78+
79+
```
80+
src/
81+
content/blog/*.md # posts (frontmatter: title, date, description, draft)
82+
site.config.ts # title, bio, nav, social links — the file you edit
83+
lib/repo.ts # auto-detects owner/repo from git remote
84+
components/Comments.tsx # the GitHub-Issues comment widget (Preact island)
85+
pages/ # index, blog/[...slug], about, 404
86+
```
87+
88+
### License
3589

36-
## 评论功能
37-
评论这个功能我是取巧了,利用Github API在项目issues下新建comment来存储,实现了原本需要第三方插件才能完成的功能.
38-
## 许可
3990
MIT
40-
4191

92+
---
93+
94+
## 中文
95+
96+
### 特性
97+
98+
- **真正的静态站点** — 用 [Astro](https://astro.build) 构建，产物是纯
99+
HTML/CSS/JS，部署到 GitHub Pages。
100+
- **写 Markdown 就是发文章** — 把文件放进 `src/content/blog/`，站点自动展示，
101+
按 frontmatter 里的 `date` 排序（不再需要调用 GitHub API 猜测发布时间——
102+
Astro 在构建期就已经知道）。
103+
- **借用 GitHub Issues 做评论** — 每篇文章对应一个 Issue，评论直接调用
104+
GitHub API，不经过任何你自己的服务器。
105+
- **Fork 即用，零配置** — owner/repo 在构建时通过 `git remote` 自动识别
106+
（见 `src/lib/repo.ts`），fork 完 push 上去就能跑。
107+
- **明暗双主题**、响应式布局，除评论组件外没有额外的阻塞 JS。
42108

109+
### 快速开始
43110

111+
1. Fork 本仓库，改名为 `<你的GitHub用户名>.github.io`。
112+
2. 仓库 Settings → Pages，Source 选择 **GitHub Actions**（已经写好的
113+
`.github/workflows/deploy.yml` 会自动完成构建和部署）。
114+
3. 编辑 `src/site.config.ts`——标题、简介、社交链接。这是唯一需要手动改的
115+
文件，owner/repo 不在里面，因为会自动识别。
116+
4. 写一篇文章：
117+
```
118+
src/content/blog/my-first-post.md
119+
```
120+
```yaml
121+
---
122+
title: "我的第一篇文章"
123+
date: 2026-07-04
124+
description: "列表页展示的一句话简介"
125+
---
126+
你好，世界。
127+
```
128+
5. `git push`，GitHub Actions 会自动构建部署，一两分钟后
129+
`https://<你的用户名>.github.io` 就能访问了。
44130

131+
本地开发：`npm install && npm run dev`。
132+
133+
### 评论功能是怎么做的
134+
135+
GitHub 早已彻底下线了密码方式的 API 认证，用户名+密码走 Basic Auth 的方式
136+
现在完全走不通了，因此改用 **Classic Personal Access Token（经典个人访问
137+
令牌）**：
138+
139+
1. 评论者点击评论框里的"Generate one"，会打开 GitHub 的令牌创建页，并预先
140+
勾好 `public_repo` 权限。
141+
2. 令牌粘贴进页面后只保存在当前标签页的 `sessionStorage` 里——直接从浏览器
142+
发往 `api.github.com`，不经过你的任何服务器。
143+
3. 第一条评论会自动创建一个标题为 `[TinyBlog] <文章slug>` 的 Issue，之后
144+
所有人的评论都发到这同一个 Issue 下。
145+
146+
**安全提示：** 带 `public_repo` 权限的经典令牌可以对你有权限的**任意**公开
147+
仓库开 issue/PR，不只是这一个——这是 GitHub 经典令牌本身的限制（不支持限定
148+
单仓库）。建议评论者用专门为此创建、用完即撤销的令牌，或者改用
149+
fine-grained token，把权限精确限定到这一个仓库的 "Issues: read and write"。
150+
151+
读取评论不需要登录，公开可见（GitHub 匿名 API 限额是每个 IP 每小时 60
152+
次）——对个人博客的访问量完全够用。
153+
154+
### 项目结构
155+
156+
```
157+
src/
158+
content/blog/*.md # 文章（frontmatter: title, date, description, draft）
159+
site.config.ts # 标题、简介、导航、社交链接——需要手动编辑的文件
160+
lib/repo.ts # 从 git remote 自动识别 owner/repo
161+
components/Comments.tsx # GitHub Issues 评论组件（Preact island）
162+
pages/ # index、blog/[...slug]、about、404
163+
```
164+
165+
### 许可
166+
167+
MIT

‎astro.config.mjs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { defineConfig } from "astro/config";
2+
import preact from "@astrojs/preact";
3+
4+
// Zero-config: no `site`/`base` needed for a `<user>.github.io` repo,
5+
// since it's served from the domain root. If you fork this into a
6+
// *project* page (`github.io/<repo>`), set `base: "/<repo>/"` below.
7+
export default defineConfig({
8+
integrations: [preact()],
9+
});

0 commit comments

Comments
 (0)