当个人知识库越来越大,积累下来的「精品笔记」如何低成本地同步到公开博客?本文以一个真实跑通的案例——
kj-knowledge(Obsidian 知识库)自动同步到yourblog.github.io(Quartz 博客)——拆解这套双仓库 + GitHub Actions 流水线的完整机制。
为什么要造这么一套东西
我的知识库和博客,本质上是两个不同性质的东西:
| 知识库(kj-knowledge) | 博客(yourblog.github.io) | |
|---|---|---|
| 定位 | 内部沉淀,草稿、过程、临时想法都往里放 | 公开输出,只放「精品」 |
| 读者 | 只有我自己 | 全世界 |
| 内容标准 | 低,随时可写 | 高,经过提炼 |
| 是否全量公开 | 否 | 只公开精选 |
核心矛盾:知识库是”全量”的,博客是”精选”的。如果简单地把整个知识库同步到博客,会把草稿、内部思考、半成品全暴露出去。所以这套系统的第一设计原则就是:内容由作者显式标记,只有打上 publish: true 的笔记才会外发。
第二个诉求是零操作。我不想每次写完一篇精品,还要手动去博客仓库复制、提交、推送。理想状态是:写完笔记,push 到知识库,剩下的全自动——博客自己更新、自己部署。
整体架构:双仓库 + 流水线
┌─ kj-knowledge(知识库)──────────────┐ ┌─ yourblog.github.io(博客)────────┐
│ Obsidian 笔记(Markdown) │ │ Quartz 源码(main 分支) │
│ ▲ 标记 publish: true 的算精品 │ │ content/ ← 精品笔记(流水线管理) │
│ │ │ │ content/index.md ← 精选首页(保留)│
│ .github/workflows/sync-to-blog.yml │ │ .github/workflows/deploy.yml │
│ push 到 main → 收集精品 → 推入博客 │ ────▶ │ push 到 main → 构建 → 部署 Pages │
└─────────────────────────────────────┘ └────────────────────────────────────┘
两个仓库各司其职,靠一条触发链串起来:
写了笔记 → push 到 kj-knowledge main
→ sync-to-blog 流水线:收集 publish:true 的笔记 → 推送到博客仓库 content/
→ deploy 流水线:Quartz 构建 → 部署到 GitHub Pages
→ https://yankj.github.io/... 可访问
全程没有常驻服务器,全靠 GitHub Actions 的事件驱动。下面逐个拆解四个机制。
机制一:选择性发布(publish: true 标记)
最核心的机制是精品标记。Obsidian 笔记自带 YAML frontmatter(--- 包裹的区块),我们在里面加一个字段:
---
publish: true
---
# 笔记标题
正文...publish: true 是一条显式的发布声明:「这篇我确认过,可以公开」。没有这个标记的笔记(草稿、内部思考、半成品)就留在知识库里,不会被同步。
这套设计的精妙之处在于:
- 作者主动选择的粒度——不是”除黑名单外全公开”,而是”白名单才公开”,默认不外发,更安全。
- 和写作流程天然融合——写笔记时顺手加一行 frontmatter,不需要任何额外工具。
机制二:收集脚本 collect-published.mjs
同步的第一步,是从知识库里筛出所有 publish: true 的笔记。用 Node 脚本实现:
// 遍历目录,解析 frontmatter,把 publish:true 的笔记按相对路径复制到输出目录
function hasPublishTrue(file) {
const content = readFileSync(file, "utf-8")
if (!content.startsWith("---")) return false
const end = content.indexOf("\n---", 3)
if (end === -1) return false
const fm = content.slice(3, end) // 取出 frontmatter 区块
return /\bpublish\s*:\s*true\b/.test(fm) // 判断是否声明发布
}关键点:
- 解析 frontmatter:从
---到\n---之间的区块里正则匹配publish: true。 - 保留相对路径:
concept/agent/agent-runtime.md复制后仍是concept/agent/agent-runtime.md,这样博客的 URL 路径和知识库保持一致,好维护。 - 跳过程序目录:
.git、.obsidian、.github、node_modules等不参与扫描。
这一步是纯本地、纯读操作,不涉及网络,所以即使后面 token 没配好,它也能正常跑、也能诊断。
机制三:同步工作流 sync-to-blog.yml
这是整条流水线的核心。它做的事情是:把收集到的精品笔记,推送到博客仓库。
触发条件
on:
push:
branches:
- main # 每次 push 到 main 自动触发
workflow_dispatch: # 也支持手动触发步骤拆解
- checkout 知识库:拉取当前代码。
- 运行收集脚本:筛出
publish: true的笔记到临时目录。 - clone 博客仓库:用 PAT 拉取博客仓库的
main分支。 - 替换 content 内容:清空博客
content/下除index.md外的所有文件(避免已取消发布的笔记残留),再把收集到的笔记复制进去。 - commit + push:提交并推回博客仓库
main——这里会触发博客的 deploy 流水线。
跨仓库推送:为什么必须用 PAT
这是整套机制里最反直觉的一个技术点。GitHub Actions 自带一个 GITHUB_TOKEN,很多新手想用它来推送。但它的作用域是当前仓库——在 kj-knowledge 的流水线里,GITHUB_TOKEN 只能操作 kj-knowledge,推不进 yourblog.github.io。
要跨仓库推送,必须用个人访问令牌(PAT),配置成仓库的 secret:
env:
BLOG_REPO_TOKEN: ${{ secrets.MYGITHUBIOBLOG }} # PAT 存进 secret推送到博客仓库时,把 PAT 拼进 URL 作为认证:
git clone --depth 1 --branch main \
"https://x-access-token:${BLOG_REPO_TOKEN}@github.com/yourname/yourblog.github.io.git" \
/tmp/blog机制四:部署工作流 deploy.yml(博客仓库)
博客仓库自己有一条部署流水线,监听 main 分支的 push。它用 Quartz 作为静态站点生成器:
permissions:
contents: read
pages: write # 部署到 Pages 需要
id-token: write # 需要 OIDC 令牌
steps:
- checkout
- npm ci # 安装依赖
- npx quartz build # 生成静态站点到 public/
- upload-pages-artifact # 上传构建产物
- deploy-pages # 部署到 GitHub Pages为什么选 Quartz:它是 Obsidian 原生的静态博客生成器,原生支持 wikilink [[...]]、callout 等 Obsidian 语法,content/ 直接就是 Markdown 文件夹。同步流水线把笔记塞进 content/,Quartz 自动把它们渲染成页面。
到这里,整条链闭环了:push 知识库 → 同步 → 推送 → 构建 → 部署 → 线上可访问。
扩展:换一个主题
Quartz 默认只有一套观感,但它有生态——saberzero1/quartz-themes 把 Obsidian 社区的大量主题适配到了 Quartz,页面风格、配色、字体都能换。macOS 风格的主题就是其中之一。
第一步:安装主题包。@quartz-themes/core 是核心插件(装一次),@quartz-themes/<主题名> 是具体主题:
npm install @quartz-themes/core @quartz-themes/macos第二步:在配置里启用。 Quartz 5 的主题配置在 quartz.config.default.yaml 的 plugins: 区块。模板默认自带一个禁用的 @quartz-themes/core 示例(tokyo-night),把它启用并把主题改成目标主题即可:
plugins:
- source: "@quartz-themes/core"
enabled: true # 原来是 false,改成 true
options:
theme: macos # 主题名
mode: both # both=亮暗双模式 / dark / light补充两点:
mode按主题定:亮/暗双支持的主题用both;只支持亮或只支持暗的主题要设成light或dark,否则会有色块异常。- 有变体的主题要加
variation:比如 Catppuccin 有latte/frappe/mocha等多个变体,需额外指定variation。
第三步:本地构建验证,再提交推送博客仓库,deploy 流水线会自动重新部署:
npx quartz build # 确认无报错,public/ 生成的主题样式正确怎么判断主题生效?构建产物 public/static/*.css 里会出现该主题的特征变量,比如 macos 主题会生成 --macos-accent 这一类变量——能搜到就说明渲染进去了。
完整的主题列表(几十个,含在线预览)在 saberzero1/quartz-themes 的 README 兼容表里,每个主题都能直接 npm i @quartz-themes/<名字> 安装。
两个真实踩过的坑(也是最有价值的经验)
坑一:secrets 不能用在 if: 条件里
最初同步流水线每个步骤都写 if: ${{ secrets.BLOG_REPO_TOKEN != '' }},想实现”没配 token 就跳过推送”。结果 workflow 在 GitHub 上加载阶段就失败(0 秒报错,连 jobs 都没有),非常隐蔽。
原因:GitHub Actions 的 if: 条件不允许访问 secrets 上下文。诊断时用 actionlint(GitHub Actions 的 lint 工具)一秒定位:
context "secrets" is not allowed here. available contexts are "env", "github", ...
修复:先把 secret 提升到 job 级 env,if: 里判断 env,run: 里用 shell 变量:
jobs:
sync:
env:
BLOG_REPO_TOKEN: ${{ secrets.MYGITHUBIOBLOG }}
steps:
- name: Clone blog repo
if: ${{ env.BLOG_REPO_TOKEN != '' }} # 用 env 判断,不用 secrets
run: |
git clone "https://x-access-token:${BLOG_REPO_TOKEN}@..." /tmp/blog坑二:PAT 没有写权限,push 一直 403
token 配好后,clone 成功了,但 push 一直报 Permission to yourname/yourblog.github.io.git denied。为什么 clone 能成功、push 失败?
因为clone 一个公开仓库不需要任何权限,但 push 需要写权限。这个 token 是个空 scope 的 token——创建时没勾任何权限。
诊断:用 curl 看 token 的 scope:
curl -sI -H "Authorization: Bearer <token>" https://api.github.com/user | grep -i "^x-oauth-scopes"- 返回
x-oauth-scopes: repo→ token 有完整写权限 ✅ - 返回空 → token 没有任何写权限 ❌
修复:创建 classic token 时勾上 repo scope(完整仓库写权限),把新 token 重新填进 secret。
教训:跨仓库推送的排错,第一步永远是确认 token 的 scope,而不是猜网络问题。 空 scope 的 token 能读公开仓库,极具迷惑性。
这套模式的适用场景与边界
适合:
- 个人用 Obsidian 类工具沉淀知识,想低成本同步精品到博客。
- 内容以 Markdown 为主,接受 GitHub Pages 托管。
- 想要”push 即发布”的零操作体验。
边界与代价:
- 需要 PAT:跨仓库推送是唯一的手工凭证环节,token 要自己维护、过期要更新。
- 粒度是整篇笔记:
publish: true是整篇发布,做不到”一篇文章里只公开某几段”。 - 全量替换:同步策略是”清空 content/ 再复制”,所以博客仓库里除
content/index.md外的内容都归流水线管,不适合混放其他页面。 - 托管在 GitHub:依赖 GitHub Actions 和 Pages,不是完全自托管的方案。
总结
这套流水线的本质,是用”显式发布标记 + 事件驱动的流水线”弥合了”内部全量沉淀”和”对外精选输出”之间的鸿沟。核心机制就四个:
publish: true标记——内容由作者显式声明,默认不外发。- 收集脚本——从知识库筛出精品,按相对路径复制。
- 同步工作流——用 PAT 跨仓库推送,触发链表起来。
- 部署工作流——Quartz 构建 + Pages 部署,让博客自动上线。
最值得记住的,不是某个具体工具,而是两个反直觉的经验:跨仓库推送必须用 PAT(自带 token 作用域不够);secrets 不能用于 if: 条件(要提升到 job 级 env)。理解了这两点,任何”知识库 → 博客”的自动化同步都能踩通。
本文对应的可运行代码:kj-knowledge/scripts/collect-published.mjs 与 .github/workflows/sync-to-blog.yml。
参考来源
- Quartz — Obsidian 原生静态博客生成器
- GitHub Actions 文档 — workflow 语法与 secrets 上下文限制
- actionlint — GitHub Actions workflow 静态检查工具
- saberzero1/quartz-themes — Quartz 主题生态