chore: rewrite README and add Makefile for AI-friendly workflow

2026-04-30 18:20:44 +01:00
parent 6583d0e4ef
commit 114e1938e5
2 changed files with 112 additions and 1 deletions
@@ -1,3 +1,67 @@
 # blog

-Hugo blog (gnoc-managed)
+Fam 的博客源码 (Hugo + PaperMod 主题),线上 https://famzheng.me/。
+
+## 写一篇文章
+
+```bash
+make new SLUG=hello-world TITLE='你好，世界' SUMMARY='第一篇,随便聊聊'
+$EDITOR content/posts/hello-world.md      # 写正文 (markdown)
+make publish MSG='post: hello world'      # commit + push,触发 CI
+```
+
+约 1 分钟后文章在 `https://famzheng.me/posts/<slug>/` 上线。
+CI 状态: <https://famzheng.me/gitea/fam/blog/actions>
+
+## 目录
+
+```
+content/posts/                # 文章 markdown,文件名 = URL slug
+hugo.toml                     # 站点配置 (baseURL, 主题选项, social 链接)
+layouts/                      # 主题 override (尽量别动)
+static/                       # favicon 等公开资源
+themes/PaperMod/              # 主题 (git submodule, 尽量别动)
+.gitea/workflows/publish.yml  # CI: hugo build -> rsync 到 /var/gnoc/hugo-public/
+```
+
+## Frontmatter
+
+每篇文章顶部 YAML:
+
+```yaml
+---
+title: "标题"
+date: 2026-04-30T10:00:00+01:00
+draft: false
+summary: "一句话摘要 (可选,影响列表页和 og:description)"
+---
+```
+
+`make new` 会填好这四个字段,你只需要写正文。
+
+## 文风 (供 AI 参考)
+
+- 第一人称、口语化,不要 AI 流水账
+- 标题简洁,正文别堆 emoji
+- 长度 500-2000 字偏多,宁短勿长
+- 写之前先扫一眼 `content/posts/*.md` 已发文章,对齐 Fam 的语气
+
+## 部署机制
+
+```
+git push origin main
+  → Gitea 触发 .gitea/workflows/publish.yml
+  → host shell act_runner (gnoc 用户, 在 famzheng.com 节点)
+  → 装 hugo 0.147.6 extended → hugo --minify --gc → rsync public/ /var/gnoc/hugo-public/
+  → k8s gnoc-hugo/hugo (nginx) hostPath 直出
+  → ingress famzheng.me/ 命中
+```
+
+## 本地预览 (可选)
+
+需要 hugo 0.147.6 extended:
+
+```bash
+make serve    # http://localhost:1313, 热重载, draft 也能看
+make build    # 一次性 build 到 public/, sanity check
+```