Obsidian on Ranch's Blog

Obsidian + GitHub + Hugo 博客发布工作流

Sat, 04 Jul 2026 08:00:00 +0800

Obsidian + GitHub + Hugo 博客发布工作流

引言

将 Obsidian 知识库中的笔记发布到个人博客，涉及三个角色的协作：

角色	位置	职责
Obsidian 知识库	本地`ai_wiki/`	笔记的创作与存储
GitHub 仓库	`Ranch007.github.io`	Hugo 博客源码 + Git 版本管理
GitHub Actions	CI 构建	自动编译 Hugo 并部署到 gh-pages

从 Obsidian 写笔记到博客上线，全自动无需手动操作博客仓库。

正文

1. 整体架构

┌─────────────────────┐     "发布到博客"      ┌──────────────────────┐
│   Obsidian Vault    │ ──────────────────→   │  Ranch007.github.io  │
│   ai_wiki/          │    publish-to-blog    │  Hugo 博客源码仓库   │
│                     │    .ps1 脚本执行      │                      │
│   wiki/             │                      │  content/post/       │
│   ├── it-tech/      │   1. 扫描 publish:    │  ├── xxx/index.md   │
│   ├── finance/      │      true 笔记         │  ├── yyy/index.md   │
│   └── reading/      │   2. 转换 frontmatter  │  └── ...            │
│                     │   3. 拷贝配图          │                      │
│   publish: true ────│   4. git commit & push │                      │
└─────────────────────┘                       └───────┬──────────────┘
                                                       │ push main
                                                       ▼
                                              ┌─────────────────────┐
                                              │  GitHub Actions     │
                                              │  deploy.yaml        │
                                              │                     │
                                              │  Hugo Extended      │
                                              │  v0.139.0 build     │
                                              │                     │
                                              │  → gh-pages 分支    │
                                              └─────────────────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────────┐
                                              │  GitHub Pages       │
                                              │  ranch007.github.io │
                                              └─────────────────────┘

2. Hugo 博客站

博客仓库：Ranch007.github.io

主题

使用 CaiJimmy/hugo-theme-stack，以 Git 子模块方式引入：

# .gitmodules
[submodule "themes/hugo-theme-stack"]
    path = themes/hugo-theme-stack
    url = https://github.com/CaiJimmy/hugo-theme-stack

克隆时需初始化子模块：

1
2

git clone https://github.com/Ranch007/Ranch007.github.io.git
git submodule update --init

站点配置 (hugo.yaml) 关键点

配置项	值	说明
`theme`	`hugo-theme-stack`	Stack 主题
`DefaultContentLanguage`	`zh-cn`	简体中文
`hasCJKLanguage`	`true`	中日韩语言支持，影响`.Summary` 和 `.WordCount`
`baseurl`	`http://ranch007.github.io`	站点根 URL
`permalinks.post`	`/p/:slug/`	博文 URL 结构
`pagination.pagerSize`	`6`	每页文章数

评论系统

基于 giscus（GitHub Discussions）：

comments:
  provider: giscus
  giscus:
    repo: Ranch007/Message-Boards
    mapping: pathname
    lang: zh-CN

使用独立的留言板仓库 Ranch007/Message-Boards，与博客仓库解耦。

侧边栏与头像

sidebar:
  subtitle1: "知是行之始"
  subtitle2: "行是知之成"
  avatar:
    src: https://github.com/Ranch007.png  # GitHub 头像

使用了两个副标题来呈现个人格言。

内容目录结构

content/
├── _index.md              # 首页
├── _index.zh-cn.md        # 中文首页
├── post/                  # 博文（page bundle 结构）
│   └── 文章slug/
│       └── index.md       # 博文正文 + 配图
├── page/                  # 独立页面
│   ├── about/             # 关于
│   ├── archives/          # 归档
│   ├── links/             # 友链
│   └── talk/              # 留言板
├── categories/            # 分类聚合页
│   ├── 网络技术/
│   ├── 投资理财/
│   └── 阅读随记/
└── tags/                  # 标签聚合页

博文使用 Hugo page bundle（每篇文章独立目录），方便携带封面图和资源文件。

分类体系

博客侧边栏显示的三个分类，与 Obsidian wiki 的三个兴趣方向一一映射：

Obsidian wiki 子目录	Hugo 分类
`wiki/it-tech/`	网络技术
`wiki/finance/`	投资理财
`wiki/reading/`	阅读随记

3. 发布脚本详解

核心脚本位于 meta/scripts/publish-to-blog.ps1，做一次性全量发布而非增量同步。

3.1 执行入口

触发词：“发布到博客”或“publish”。

动作（定义在 meta/CLAUDE.md 触发 4）：

AI 在笔记 frontmatter 添加 publish: true
运行 meta/scripts/publish-to-blog.ps1
脚本扫描 → 转换 → 复制 → git push
源笔记 publish: true → published: true

3.2 扫描阶段

Get-ChildItem -Path $WikiDir -Recurse -Filter "*.md" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    # 正则匹配 frontmatter 中的 publish: true
    if ($frontmatter -match "(?m)^publish:\s*true$") {
        $toPublish += $_
    }
}

递归扫描 wiki/ 下所有 .md 文件，正则匹配 frontmatter 中 publish: true 字段。

3.3 Frontmatter 转换（Obsidian → Hugo）

Obsidian 字段	Hugo 字段	转换规则
`title`	`title`	原样保留
`published`	`date`	取`published`，无则取 `created`，均无则当天
`tags`	`tags`	原样保留，过滤掉`publish` 标签
`description`	`description`	原样保留
—	`slug`	由标题和日期生成
—	`image`	正文第一张图片
—	`categories`	根据 wiki 子目录自动映射

生成的 Hugo frontmatter 示例：

---
title: "Obsidian 个人知识库搭建全记录"
slug: "2026-07-04-Obsidian-个人知识库搭建全记录"
description: ""
date: "2026-07-04T08:00:00+08:00"
image: cover.jpg
math:
license:
hidden: false
draft: false
categories: ["网络技术"]
tags: [""]
---

3.4 正文转换

Wiki-link 转换：所有 Obsidian 内部链接转为标准 markdown 链接：

# [显示文字](链接.md) → [显示文字](链接.md)
$body = [regex]::Replace($body, '\[\[([^\]|]+)\|([^\]]+)\]\]', '[${2}](${1}.md)')
# [链接](链接.md) → [链接](链接.md)
$body = [regex]::Replace($body, '\[\[([^\]|]+)\]\]', '[${1}](${1}.md)')

Dataview 剥离：dataview 和 dataviewjs 代码块不兼容 Hugo，直接移除：

1
2

$body = $body -replace '(?s)', ''
$body = $body -replace '(?s)', ''

图片处理：内嵌图片 ![assets/xxx](assets/xxx.md) 处理逻辑：

第一张图片 → 封面图（复制到 post 根目录，写入 image 字段）
其余图片 → 复制到 post_slug/assets/ 子目录
图片引用转为 ![](图片名) 的相对路径
如果在 assets 指定路径未找到，递归搜索 assets 所有子目录

$body = [regex]::Replace($body, '!\[\[assets/([^\]]+)\]\]', {
    # 图片存在 → 复制 + 替换引用
    # 第一张图 -> featuredImage（封面）
    # 其余图 -> assets/ 子目录
    # 不存在 → 报错并保留原样
})

空行清理：连续三个以上换行压缩为两个。

3.5 Slug 生成算法

function Get-Slug {
    param([string]$Title, [string]$DateStr)
    # 保留中英文、数字和空格
    $clean = $Title -replace '[^\w一-鿿\s-]', ''
    # 空格替换为 -
    $clean = $clean.Trim() -replace '\s+', '-'
    if ([string]::IsNullOrWhiteSpace($clean)) { $clean = "post" }
    return "$DateStr-$clean"
}

最终 URL 格式：

`1`	`https://ranch007.github.io/p/{slug-lowercase-urlencoded}/`

例如 2026-07-04-Obsidian 个人知识库搭建全记录 → URL 编码后变为：

`1`	`https://ranch007.github.io/p/2026-07-04-obsidian-个人知识库搭建全记录/`

3.6 源笔记标记

发布成功后，源笔记的 publish: true 被替换为 published: true：

`1`	`$newContent = $content -replace '(?m)^publish:\strue\s$', 'published: true'`

这确保了同一篇笔记不会重复发布，并在 frontmatter 中保留了发布记录。

3.7 博客数据同步

脚本同步更新 vault 内的 meta/blog-posts.md：

<!-- 此文件由 publish-to-blog.ps1 自动维护 -->

总篇数: 1

## 最新发布
- [文章标题](https://ranch007.github.io/p/slug/) — 2026-07-04

该文件被仪表盘 index.md 读取展示博客统计和最近发布。

3.8 Git 推送

脚本自动进入博客仓库目录执行：

Push-Location $BlogPath
git add -A
git commit -m "publish: N 篇博客更新"
git push
Pop-Location

推送到 main 分支后，GitHub Actions 会自动构建部署。

4. GitHub Actions 持续部署

工作流文件：.github/workflows/deploy.yaml

name: deploy

on:
  push:
    branches:
      - main        # 只有 main 分支触发

env:
  TZ: Asia/Shanghai          # 时区设置

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          submodules: true     # 拉取主题子模块
          fetch-depth: 0       # 完整 git 历史（用于 enableGitInfo）

      - name: Disable quotePath
        run: git config --global core.quotePath false  # 中文文件名不乱码

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.139.0"
          extended: true        # 必须用 extended 版（支持 SCSS）

      - name: Build
        run: hugo -D            # 构建（包括 draft 文章）

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./public
          commit_message: auto deploy

关键细节：

submodules: true — 必须拉取 hugo-theme-stack 子模块，否则构建失败
extended: true — Stack 主题使用 SCSS，需要 Hugo Extended 版
core.quotePath false — 中文文件名在 git 中不被引用转义
enableGitInfo: true — Hugo 配置中启用，利用 git 提交时间作为 lastmod
目标分支为 gh-pages，GitHub Pages 从该分支提供服务
仓库设置为 Ranch007/Message-Boards 作为 giscus 评论数据源

5. 完整发布流程（端到端）

第 1 步： 在 Obsidian 中写笔记，存入 wiki/ 对应目录 第 2 步： 告诉 AI “发布到博客” 或 “把 xxx 发布到博客” 第 3 步： AI 在笔记 frontmatter 添加 publish: true（如果指定了某篇文章） 第 4 步： AI 执行 meta/scripts/publish-to-blog.ps1 第 5 步： 脚本扫描所有 publish: true 笔记： - 转换为 Hugo 格式 - 复制配图 - 写入 content/post/{slug}/index.md - 标记源笔记 published: true - 更新 meta/blog-posts.md - Git add → commit → push 第 6 步： GitHub Actions 检测到 push，自动构建 Hugo → 部署 gh-pages 第 7 步： 约 1-2 分钟后博客上线

6. 关键细节总结

目录映射规则

源目录	映射为
Obsidian`wiki/`	Hugo`content/post/`
每个`publish: true` 笔记	一个 Hugo page bundle（独立目录）
Obsidian`assets/`	复制到 post bundle 内
wiki 子目录（如 it-tech）	分类标签（如"网络技术"）

前后 frontmatter 对照

源笔记（Obsidian）：

---
title: Obsidian 个人知识库搭建全记录
tags: [it-tech, obsidian, tutorial, workflow]
created: 2026-07-04
publish: true
---

发布后（Obsidian）：

---
title: Obsidian 个人知识库搭建全记录
tags: [it-tech, obsidian, tutorial, workflow]
created: 2026-07-04
published: true
---

博客端（Hugo）：

---
title: "Obsidian 个人知识库搭建全记录"
slug: "2026-07-04-Obsidian-个人知识库搭建全记录"
date: "2026-07-04T08:00:00+08:00"
categories: ["网络技术"]
tags: [""]
draft: false
---

本地预览博客

1
2
3

cd Ranch007.github.io
hugo server -D
# 访问 http://localhost:1313

拓展

局限性

目前是一次性全量扫描发布，不支持增量差异发布
publish 脚本是 PowerShell（Windows 限定），跨平台需适配
Wiki-link 转换后，博客端链接指向本地 .md 文件而非实际页面
如果笔记中有多条 publish: true 同时发布，会作为一次 git commit
封面图依赖 Unsplash API 自动搜索（由 AI 执行），脚本本身不包含此逻辑

后续可能优化

支持只在笔记变更时增量复制（通过 git diff 判断）
添加博客端链接重写为实际 URL 的能力
支持自定义 slug 覆盖（通过 frontmatter 字段）
发布前预览：在本地构建 Hugo 并预览效果再推送

附录

参考文章

wiki/it-tech/notes/obsidian-wiki-setup-guide — Obsidian 个人知识库搭建全记录（已发布到博客）
wiki/it-tech/notes/obsidian-ai-plugin-skill-guide — Obsidian AI 知识库所用插件与 Skills 清单
CaiJimmy/hugo-theme-stack — Stack 主题
peaceiris/actions-hugo — Hugo GitHub Action
peaceiris/actions-gh-pages — GitHub Pages 部署 Action

版权信息

本文原载于 Ranch's Blog，遵循 CC BY-NC-SA 4.0 协议，复制请保留原文出处。

Obsidian 个人知识库搭建全记录

Sat, 04 Jul 2026 08:00:00 +0800

Obsidian 个人知识库搭建全记录

引言

基于 Karpathy LLM Wiki 方法论，在 Obsidian 中搭建 AI 辅助个人知识库的完整过程。记录了每个阶段的真实决策、踩过的坑和最终方案。

正文

让 AI 阅读方法论并设计结构

你：阅读Karpathy wiki 方法论，帮我把仓库里的wiki文件夹的结构给建立起来

AI 读完后，按照 Karpathy 的三层架构（raw / wiki / schema）设计了初始目录。经过讨论，确定了三个兴趣方向：

1
2
3

it-tech/    ← IT 技术（编程、框架、工具、架构）
finance/    ← 投资理财（概念、策略、标的分析）
reading/    ← 阅读随记（书籍、文章、跨书主题）

初始结构采用了严格的嵌套方案，后来扁平化调整，去掉了多余层级。

目录演变

初始方案（三层嵌套）            最终方案（扁平）
─────────────────             ────────────────
ai_wiki/                      ai_wiki/
├── wiki/                     ├── raw/          ← 原始资料
│   ├── raw/                  ├── wiki/         ← 知识库
│   ├── wiki/                 │   ├── it-tech/
│   │   ├── it-tech/          │   ├── finance/
│   │   ├── finance/          │   └── reading/
│   │   └── reading/          ├── assets/       ← 配图
│   └── meta/                 └── meta/

第一篇素材

在 raw/ 放入第一篇资料后直接说 ingest，AI 自动完成：归类子目录 → 读取内容 → 创建概念页 + 实体页 → 更新索引 → 写日志。

发现 raw/ 根目录需要整理

使用 Obsidian Web Clipper 剪藏的笔记直接掉进 raw/ 根目录，杂乱无章。于是加了一条规则：

每次 Ingest 时，自动将 raw/ 根目录下的未分类笔记按内容归类到对应子目录。

写入 meta/CLAUDE.md，从此再也不用手动分类。

merge 外部 CLAUDE.md

发现 helloianneo/obsidian-ai-second-brain 的 CLAUDE.md 更完整，将其与本地规则合并，形成了当前 meta/CLAUDE.md 的基础。

索引页的演变

最初的 index.md 只是一个简单的文章列表：

1
2
3

## IT技术
- [概念页](概念页.md) — 说明
- [实体页](实体页.md) — 说明

用了几个来回后，逐步进化成了动态仪表盘。

踩过的坑

问题	原因	解决
仪表盘完全不显示	未启用 DataviewJS 查询	Dataview 设置 → 开启 Enable Dataview JavaScript queries
CSS 不生效	`cssclasses` 应写作 `cssclass`（单数）	修正 frontmatter key
统计卡片对不齐	`dv.el({container})` 参数不可靠	改用`document.createElement` + `dv.container.appendChild`
整个 DVJS 块不渲染	模板字符串内嵌 IIFE 解析失败	把逻辑提到外面先算好
用户名读取报错	`require('os')` 在 Obsidian 中不可用	改用`app.vault.adapter.basePath` 提取
底部索引不显示	用`document.createElement` 但忘了 `appendChild`	创建元素后要手动附加到容器

功能模块迭代顺序

统计卡片 → 文章数、资料数、总计，三列等宽 Grid
兴趣方向 → 各区域文章数 + 标签列表
主题切换 → 🌙 emoji 按钮，一键切换深色/浅色
最近更新 → 按修改时间排序，显示相对时间
每日诗句 → 从诗词歌赋.md 按天轮换
随机索引 → 每天随机展示各区域最多 5 篇
知识图谱 → 点击跳转 Obsidian 关系图谱

主题切换

最初用文字按钮，后来改为纯 emoji 切换：

btn.onclick = () => {
  const isDark = document.body.classList.contains('theme-dark');
  document.body.classList.toggle('theme-dark', !isDark);
  document.body.classList.toggle('theme-light', isDark);
  btn.textContent = isDark ? '☀️' : '🌙';
};

每日诗句

从 wiki/reading/books/诗词歌赋.md 读取，以当天日期为种子选一行，同一天不重复：

const content = await dv.io.load("wiki/reading/books/诗词歌赋.md");
const poemLines = content.split('\n').filter(l => /^\s*\d+\./.test(l));
const d = Math.floor((new Date() - new Date(new Date().getFullYear(), 0, 0)) / 86400000);
const raw = poemLines[d % poemLines.length].replace(/^\s*\d+\.\s*/, '').trim();

问候语按时间段切换

时间段	问候
7:00–8:59	👋 早上好
9:00–10:59	👋 上午好
11:00–12:59	👋 中午好
13:00–16:59	👋 下午好
17:00–22:59	👋 晚上好
23:00–6:59	👋 夜深了，早点休息吧

用户名自动读取

从 vault 路径 C:\Users\{userName}\... 提取，不硬编码：

1
2

const userName = (app.vault.adapter.basePath || '')
  .match(/[\\/]Users[\\/]([^\\/]+)/)?.[1];

meta/CLAUDE.md 的演变

从一个简单规则文件逐步演变成完整的工作手册：

版本	新增内容
v1	Web Clipper 分类规则
v2	merge 外部 CLAUDE.md（Ingest / Query / Lint 三大触发行为）
v3	唤醒自动检查（哈喽/hello 触发）
v4	图片管理规则（命名、分类、外链处理）
v5	Frontmatter 规范（created / published）
v6	精简冗余规则，保留核心流程
v7	log.md 改为新条目插最前面

Frontmatter 规范

---
title: 页面标题
tags: [主分类, 子分类]
created: 2026-07-04       # 我在 wiki 建页日期
published: 2024-06-21     # 原始资料发布日期（有时效性内容必填）
sources:
  - raw/主题/来源文件名.md
---

assets/ 目录建立

assets/
├── it-tech/       ← IT 技术配图
├── finance/       ← 理财配图
└── reading/       ← 阅读配图

不按页面类型细分，一张图可能被多处引用。

命名规范

格式：文章缩写-编号.扩展名

xbi-analysis-01.webp
xbi-analysis-02.webp
xbi-analysis-03.webp
xbi-analysis-04.png

图片管理流程

Web Clipper 剪藏后按 Ctrl+Shift+D 下载附件到 assets/
Ingest 时检查外链图片，提示下载到本地
散落的图片移入对应主题子目录
引用路径统一为 ![assets/主题/xxx.png](assets/主题/xxx.png.md)

初始化目录结构

你：阅读Karpathy wiki 方法论，帮我把仓库里的wiki文件夹的结构给建立起来

灌入第一篇资料

你： ingest

搭建仪表盘

你：我想调整obsidian的面板，更美观，更能展现我的wiki

你：我希望有一个切换深色/浅色主题的按钮

你：仪表盘能加上每天展示一行诗句，从诗词歌赋.md读取

日常 Ingest

你： ingest

健康检查

你：检查一下wiki是否搭建完善，做一轮健康检查

添加自定义规则

你：我使用Obsidian Web Clipper，网页笔记会直接放到raw/，你更新的时候把源笔记也在raw里面分类一下，写成一条规则到meta/CLAUDE.md

唤醒自动检查

你：哈喽

查询知识库

你：我想查询一下为什么房价会跌

拓展

（留空，按需补充）

附录

参考文章

[raw/it-tech/Karpathy wiki 方法论](raw/it-tech/Karpathy wiki 方法论.md) — Karpathy LLM Wiki 方法论（原始 gist）
meta/CLAUDE — AI 工作规则完整版
wiki/it-tech/concepts/llm-wiki-methodology — LLM Wiki 方法论概念页
wiki/it-tech/entities/karpathy-wiki — Karpathy’s LLM Wiki 实体页
wiki/it-tech/notes/obsidian-ai-knowledge-base-guide — Obsidian + Claude AI 搭建指南（第三方）
Karpathy AI+Obsidian 知识库教程 - 栗氪聊AI — 飞书文档（第三方）
helloianneo/obsidian-ai-second-brain — CLAUDE.md 模板参考

版权信息

本文原载于 Ray’s Wiki，请遵循 CC BY-NC-SA 4.0 协议，复制请保留原文出处。

Obsidian on Ranch's Blog

Obsidian + GitHub + Hugo 博客发布工作流

Obsidian + GitHub + Hugo 博客发布工作流

引言

正文

1. 整体架构

2. Hugo 博客站

主题

站点配置 (hugo.yaml) 关键点

评论系统

侧边栏与头像

内容目录结构

分类体系

3. 发布脚本详解

3.1 执行入口

3.2 扫描阶段

3.3 Frontmatter 转换（Obsidian → Hugo）

3.4 正文转换

3.5 Slug 生成算法

3.6 源笔记标记

3.7 博客数据同步

3.8 Git 推送

4. GitHub Actions 持续部署

5. 完整发布流程（端到端）

6. 关键细节总结

目录映射规则

前后 frontmatter 对照

本地预览博客

拓展

局限性

后续可能优化

附录

相关文件

参考文章

版权信息

Obsidian 个人知识库搭建全记录

Obsidian 个人知识库搭建全记录

引言

正文

让 AI 阅读方法论并设计结构

目录演变

第一篇素材

发现 raw/ 根目录需要整理

merge 外部 CLAUDE.md

索引页的演变

踩过的坑

功能模块迭代顺序

主题切换

每日诗句

问候语按时间段切换

用户名自动读取

meta/CLAUDE.md 的演变

Frontmatter 规范

assets/ 目录建立

命名规范

图片管理流程

初始化目录结构

灌入第一篇资料

搭建仪表盘

日常 Ingest

健康检查

添加自定义规则

唤醒自动检查

查询知识库

拓展

附录

参考文章

版权信息