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`	简体中文
`hasCJKLanguage`	`true`	中日韩语言支持，影响`.Summary` 和 `.WordCount`
`baseurl`	`https://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: https://github.com/Ranch007.png  # GitHub 头像

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

内容目录结构

content/
├── _index.md              # 首页
├── _index.zh.md           # 中文首页
├── post/                  # 博文（page bundle 结构）
│   └── 文章slug/
│       └── index.md       # 博文正文 + 配图
├── page/                  # 独立页面
│   ├── about/             # 关于
│   ├── archives/          # 归档
│   ├── links/             # 友链
│   └── talk/              # 留言板
├── categories/            # 分类聚合页
│   ├── 网络工程/
│   ├── 网络安全/
│   ├── 环境部署/
│   └── 博客与建站/
└── tags/                  # 标签聚合页

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

分类体系

博客侧边栏显示的四个分类（网络工程 / 网络安全 / 环境部署 / 博客与建站），优先由笔记 frontmatter 的 category 字段决定，未指定时按 Obsidian 目录兜底：

Obsidian 来源	Hugo 分类
frontmatter `category: 网络工程`	网络工程
frontmatter `category: 网络安全`	网络安全
frontmatter `category: 环境部署`	环境部署
frontmatter `category: 博客与建站`	博客与建站
兜底：`wiki/it-tech/`	环境部署

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`	正文第一张图片
`category`	`categories`	优先取 frontmatter `category`，缺失时按目录兜底

生成的 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 内
笔记 frontmatter `category`	分类标签（如"网络工程"）

前后 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 协议，复制请保留原文出处。

自动化 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 对照

本地预览博客

拓展

局限性

后续可能优化

附录

相关文件

参考文章

版权信息