博客与建站 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`	简体中文
`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 协议，复制请保留原文出处。

【博客装修日记】Hugo➕ Stack ➕ Giscus魔改美化细节满满

Sun, 20 Oct 2024 11:55:35 +0000

💡 提示

避免踩坑的建议：

凡是需要更改的文件都从themes/主题复制到主目录（hugo new site xxx创建的那个）下

接下来的个性化配置文件建议都在博客主目录下操作，减少更新主题时个性化配置被覆盖的麻烦

每次服务启动，会同步更新所有位置配置文件，但主目录配置文件优先级最高

导入主题

安装主题一般而言存在三种方式：

git submodule 安装
go module 安装（需要安装 Go 语言）
本地安装

我个人更推荐第一种方式，考虑到后续升级的难易，这算是最均衡的一种方式。具体的安装方法可以在各主题的说明中找到，我这里安装的是【Stack】。在网站根目录下，输入：

git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ hugo-theme-stack

# 更新主题
git submodule init	//初始化子模块
git submodule update	//更新子模块到最新版本

等待下载完成后，便可以进行【配置】了。假如你想用其他方式安装，也可以参考【这里】，而且Stack本身有全英文的【说明文档】。我建议是将./themes/hugo-theme-stack/exampleSite/文件下的content和hugo.yaml直接复制到博客主目录下（这是一个作者放的例子，这里面有许多提示），根据说明与需求修改，会剩下很多时间。

基础配置

打开`hugo.yaml`

本地调试的时候baseurl可以设置为http://localhost:1313。调试完推送到GitHub上，记得改为网站根目录，有疑问请参考【这里】。

网站 `icon`、时间格式、博客头像

网站icon存储路径：/static/favcion.ico
Go语言时间格式：
博客头像存储路径：/assets/img/avatar.png

favicon、avatar的路径格式如下图所示

`License`和留言板功能

license：做好公共版权许可协议声明
comments：进入【Giscus】官网，在线安装app，进入Giscus的配置页面，根据官方提示配置留言板功能。

这里我也给出我的配置，仅供参考。Message-Boards是我新建的一个留言板专属存放的public仓库。

    comments:
        enabled: true
        provider: giscus

        giscus:
            repo: Ranch007/Message-Boards
            repoID: R_kgDONBh4yw
            category: Announcements
            categoryID: DIC_kwDONBh4y84CjbwV
            mapping: pathname
            strict: 0
            lightTheme: 0
            darkTheme: 0
            reactionsEnabled: 1
            emitMetadata: 0
            inputPosition: top
            lang: zh-CN

社交功能

加入个人社交平台的链接
icon路径：博客主目录的/assets/icons下，所有icon都在这里，都是svg文件。

主题魔改

整体布局

照抄Naive Koala老师的文章《Hugo-theme-Stack 魔改美化》，文章写的很细心也很用心，属于喂饭教程。

📝 备注

1.没有目录的自己创建一个同名目录，切记要仔细保证这些单词准确

2.代码看不懂没事，读文章尝试理解，看一下作者改的那些代码，那就是实现变动的关键点

这里涉及到复制的文件分别有：

themes\hugo-theme-stack\assets\scss\custom.scss 复制到 /assets/scss/custom.scss

themes\hugo-theme-stack\layouts\partials\footer\custom.html 复制到 /layouts/partials/footer/custom.html

themes\hugo-theme-stack\assets\scss\partials\sidebar.scss 复制到 /assets/scss/partials/sidebar.scss（这里需要下载两个icon，记得更改好指定命名保存到/assets/icons；还涉及到去代码中更改，作者有提供行数，版本不一样所以不一定准确，所以得审一下代码，注意缩进）

themes\hugo-theme-stack\layouts\partials\sidebar\left.html 复制到 /layouts/partials/sidebar/left.html

themes\hugo-theme-stack\assets\scss\grid.scss 复制到 /assets/scss/grid.scss

themes\hugo-theme-stack\layouts\index.html 复制到 /layouts/index.html

在 static 文件夹下新建 code-header.svg（macOS 风格红绿灯图标）

themes\hugo-theme-stack\assets\scss\partials\layout\article.scss 复制到 /assets/scss/partials/layout/article.scss

“显示语言和复制按钮”与代码行自带的copy重叠了，这里我没有弄

如果你想更从容一点，可以提前把上面的文件复制主目录。开始魔改前，记得整体备份一下。

一些细节

添加文章开头更新时间和字数统计

在layouts\partials\article\components\details.html文件中，红框标记的就是增添组件的代码，黄框标记的就是两个组件的icon命名（目录在/assets/icons下）

下图所示，就是增添后的文章标题组件

添加文章末尾最后更新时间

在博客主文件夹下 layouts\partials\article\components\footer.html更新下面代码：

<footer class="article-footer">
    {{ partial "article/components/tags" . }}
    {{ if and (.Site.Params.article.license.enabled) (not (eq .Params.license false)) }}
    
    <section class="article-copyright">
        {{ partial "helper/icon" "copyright" }}
        <span>{{ default .Site.Params.article.license.default .Params.license | markdownify }}</span>
    </section>
    {{ end }}

    {{- if ne .Lastmod .Date -}}
        <div>
            <section class="article-lastmod">
                {{ partial "helper/icon" "edit" }}
                    <time class="article-lastmod">
                        {{ T "article.lastUpdatedOn" }}{{- .Lastmod.Format (or .Site.Params.published "2006-01-02T15:04") -}}
                    </time>
            </section>
        </div>
    {{- end -}}
    
</footer>

通过上面代码第16行，article.lastUpdatedOn添加“最后更新于”

添加网站运行时间组件

打开layouts\partials\footer\footer.html文件，将下面代码插入

    <span id="timeDate">载入天数...</span><span id="times">载入时分秒...</span>
    <script language="javascript"> 
        var now = new Date();
        function createtime(){
            // 当前时间
            now.setTime(now.getTime()+250);
            var grt= new Date("2024/10/15 00:00:00"); //网站诞生时间
            days = (now - grt ) / 1000 / 60 / 60 / 24;
            dnum = Math.floor(days);
            hours = (now - grt ) / 1000 / 60 / 60 - (24 * dnum);
            hnum = Math.floor(hours);
            if(String(hnum).length ==1 ){hnum = "0" + hnum;}
            minutes = (now - grt ) / 1000 /60 - (24 * 60 * dnum) - (60 * hnum);
            mnum = Math.floor(minutes);
            if(String(mnum).length ==1 ){mnum = "0" + mnum;}
            seconds = (now - grt ) / 1000 - (24 * 60 * 60 * dnum) - (60 * 60 * hnum) - (60 * mnum);
            snum = Math.round(seconds);
            if(String(snum).length ==1 ){snum = "0" + snum;}

            document.getElementById("timeDate").innerHTML = "本站已稳定运行"+dnum+" 天 ";
            document.getElementById("times").innerHTML = hnum + " 小时 " + mnum + " 分 " + snum + " 秒"
        }
        setInterval("createtime()",250); 
    </script>

该组件效果展示：

左侧栏 ID 和简介换行

找到layouts\partials\footer\footer.html中下方代码，更改为

可以按照个人需求对下面代码进行调整，我将“个人ID”直接写进代码，通过更改subtitle实现换行

        <div class="site-meta">
            <h1 class="site-name"><a href="{{ .Site.BaseURL | relLangURL }}"><span>Ranch</span></a></h1>
            <h2 class="site-description">{{ .Site.Params.sidebar.subtitle1 }}<br>{{ .Site.Params.sidebar.subtitle2 }}</h2>
        </div>

实际效果展示

到这里使用Hugo➕Stack➕Giscus部署到GitHub的博客搭建和魔改美化就告一段落啦

后续如果有更新也会继续记录到Blog这个标签里

附录

参考文献

版权信息

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

【Free】使用Hugo搭建GitHub私人博客

Fri, 18 Oct 2024 22:19:18 +0000

环境准备

Git下载

进入【git官网】，找到对应适用于自己电脑系统的版本进行下载
根据提示，默认安装即可

Hugo下载

在【Hugo的GitHub官网】上，根据自己系统，选择对应版本直接下载（Tips：这里我根据【Hugo官网】的建议是安装了扩展版本）

下载后解压即可

（建议）将hugo.exe所在文件夹加入用户环境变量，方便使用hugo命令

博客搭建

创建博客

（1）在hugo.exe所在文件夹上方地址栏中，输入cmd，然后回车唤起命令行

（2）输入以下命令，创建xxx文件夹（这个文件夹就是博客的主文件夹，后面也可以改名）；并给出搭建博客的步骤

1
2

# 在当前文件夹中为创建xxx博客项目
hugo new site xxx

运行后便会输出一个网站目录，其结构为（引用自炸鸡人博客）：

cd切换进入blog\目录，输入下面命令，启动hugo服务

`1`	`hugo server -D`

Ctrl+鼠标左键点击上方链接，进入演示站点，如需停止在命令行输入Ctrl+C停止服务（hugo默认是没有主题的，后面会进行一个主题配置）

导入主题

（1）前往【Hugo Themes】，选择一个自己中意的主题

（2）安装主题一般而言存在三种方式：
1. git submodule 安装
2. 本地安装
3. go module安装（需要安装Go语言）
（3）我个人使用第一种方式，考虑到后续主题升级的难易，这算是最均衡的一种方式。具体的安装方法可以在各主题的说明中找到，我这里安装的是【Stack】。在网站目录下，输入：

# 前目录中初始化一个空的 Git 存储库
git init

# 将stack主题克隆到`themes`目录中，并将其作为Git子模块添加到当前项目中
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

等待下载完成后，便可以进行后面的配置了。假如你想用其他方式安装，也可以参考这里。Stack本身有全英文的说明文档，

（4）等待下载完成。建议将exampleSite样例数据中的`Content和hugo.yaml复制到主文件夹中

（4）进入主文件下的content\post，并删掉rich-content文件夹（不然会报错）

（5）再次启动hugo服务，查看主题。具体主题配置细节放在下一篇。

GitHub部署

常规部署

（1）前往【GitHub官网】，登录或者注册一个GitHub账号，创建新的仓库{GitHub用户名}.github.io（这里我已经注册了）

（2）前往进入xxx.github.io仓库，从Setting -> Pages先将source的“从分支部署“切换到”GitHub操作“，初始化一下，再切回“分支部署”

然后Branch出现”main分支“，选择main保存。

（Tips：现在需要先将内容推送到GitHub才能开启GitHub Pages网址。）

（3）回到本地博客的主文件夹。准备发布网站，执行以下命令，Hugo 会在public在项目根目录中创建整个静态网站

hugo -D

（4）接着在进入 public 文件夹，执行以下命令上传到github仓库上，第一次上传可能需要输入账号密码

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/{你的GitHub用户名}/{用户名.github.io}
git push -u origin main

（5）前往https://github.com/{GitHub用户名}/{用户名}.github.io，点击Branch判断有没有上传成功

自动化部署

具体要求

如果想使用 Github Actions 自动部署 hugo 博客，则最起码需要创建两个 Github 的仓库。

第①个，便是存储博客 .md 源文件的地方，其实就是 hugo的主文件；

第②个，则是部署 Github Pages 的仓库（存放public文件夹里的所有文件），仓库名必须是 <GitHub用户名>.github.io，这是 github 官方要求的。

原理流程

1.当我们提交博客 .md 源文件到仓库 ① 后，利用 Github Actions 自动执行 hugo 的命令 2.在 public 目录下会自动生成静态网站，然后再将 public 目录推送到仓库 ② 3.由于仓库② 是 Github Pages，它接着就会自动执行部署的命令。

（1）我们需要从主文件的仓库①推送到外部 GitHub Pages 仓库②，需要特定权限，所以还得在 GitHub 账户 Setting - Developer settings - Personal access tokens （https://github.com/settings/tokens）下创建一个 Token：

进入设置，Developer settings就在设置左下角，如下图点进去（需要验证）

如下图进行配置，创建一个永久性token，并复制（Tips：切记！！Token只会出现一次，请做好留存、保密）

最后，来到以github.io结尾的仓库①。添加一个 secret，保存并命名你复制的token值，这个Name下一步需要用到。

（2）管理博客主文件的仓库①，点击 Actions 按钮，即可添加工作流文件，该文件一般是以 .yml 结尾，这样才能被 GitHub 识别

我创建的文件名为deploy.yml，内容如下：

name: deploy

# 代码提交到main分支时触发github action
on:
  push:
    branches:
      - main	# 这里的意思是当 master分支发生push的时候，运行下面的jobs
      
jobs:
  deploy:	# 任务名自取
    runs-on: ubuntu-latest	# 在什么环境运行任务
    steps:
        - name: Checkout
          uses: actions/checkout@v4	# 引用actions/checkout这个action，与所在的github仓库同名
          with:
 			 submodules: true	# Fetch Hugo themes (true OR recursive) 获取submodule主题
              fetch-depth: 0	 # Fetch all history for .GitInfo and .Lastmod

      	- name: Disable quotePath
      	  run: git config --global core.quotePath false

        - name: Setup Hugo	# 步骤名自取
          uses: peaceiris/actions-hugo@v3	# hugo官方提供的action，用于在任务环境中获取hugo
          with:
              hugo-version: "latest"	# 获取最新版本的hugo
              extended: true

        - name: Build Web
          run: hugo -D	# 使用hugo构建静态网页
          
        - name: Deploy Web
          uses: peaceiris/actions-gh-pages@v4	# 一个自动发布github pages的action
          with:
              personal_token: ${{ secrets.{保存toekn的Name} }}	# 发布到其他repo需要提供上面生成的personal access token
              external_repository: {GitHub用户名}/{用户名}.github.io	# 发布到哪个repo
              publish_branch: main	# 发布到哪个branch
              publish_dir: public	# 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
              commit_message: auto deploy

这样，我们的博客网站就部署好了，这极大地简化了我们发布文章的流程。

附录

参考文献

版权信息

本文原载于 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 对照

本地预览博客

拓展

局限性

后续可能优化

附录

相关文件

参考文章

版权信息

【博客装修日记】Hugo➕ Stack ➕ Giscus魔改美化 细节满满

导入主题

基础配置

打开hugo.yaml

网站 icon、时间格式、博客头像

License和留言板功能

社交功能

主题魔改

整体布局

一些细节

添加文章开头更新时间和字数统计

添加文章末尾最后更新时间

添加网站运行时间组件

左侧栏 ID 和简介换行

附录

参考文献

版权信息

【Free】使用Hugo搭建GitHub私人博客

环境准备

Git下载

Hugo下载

博客搭建

创建博客

导入主题

GitHub部署

常规部署

自动化部署

附录

参考文献

版权信息

【博客装修日记】Hugo➕ Stack ➕ Giscus魔改美化细节满满

打开`hugo.yaml`

网站 `icon`、时间格式、博客头像

`License`和留言板功能