当个人知识库越来越大,积累下来的「精品笔记」如何低成本地同步到公开博客?本文以一个真实跑通的案例——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:   # 也支持手动触发

步骤拆解

  1. checkout 知识库:拉取当前代码。
  2. 运行收集脚本:筛出 publish: true 的笔记到临时目录。
  3. clone 博客仓库:用 PAT 拉取博客仓库的 main 分支。
  4. 替换 content 内容:清空博客 content/ 下除 index.md 外的所有文件(避免已取消发布的笔记残留),再把收集到的笔记复制进去。
  5. 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,不是完全自托管的方案。

总结

这套流水线的本质,是用”显式发布标记 + 事件驱动的流水线”弥合了”内部全量沉淀”和”对外精选输出”之间的鸿沟。核心机制就四个:

  1. publish: true 标记——内容由作者显式声明,默认不外发。
  2. 收集脚本——从知识库筛出精品,按相对路径复制。
  3. 同步工作流——用 PAT 跨仓库推送,触发链表起来。
  4. 部署工作流——Quartz 构建 + Pages 部署,让博客自动上线。

最值得记住的,不是某个具体工具,而是两个反直觉的经验:跨仓库推送必须用 PAT(自带 token 作用域不够);secrets 不能用于 if: 条件(要提升到 job 级 env)。理解了这两点,任何”知识库 → 博客”的自动化同步都能踩通。


本文对应的可运行代码:kj-knowledge/scripts/collect-published.mjs 与 .github/workflows/sync-to-blog.yml。

参考来源