我把 Obsidian 变成了个人网站：从笔记到上线，只隔一个快捷键

写作工具与发布工具共用同一套文件，「发布」就不再是负担。这篇文章复盘我从零搭起这条 Obsidian → 个人网站全自动流水线的全过程：为什么做、怎么选、踩了哪些坑、最后想明白了什么。

一、起因：写完的笔记，都去了哪里？

我日常用 Obsidian 记笔记。学一个知识点、读一篇论文、攒一周的零碎想法，都会敲进去。但时间一长，问题慢慢浮出来：

输出没有反馈。写给自己看的东西，永远发现不了表达上的漏洞，也得不到任何外部视角。
知识连不成网。笔记越攒越多，却是一座座孤岛，翻旧笔记全靠搜索框碰运气。
没有积累感。学了一整年，想回顾、想展示的时候，拿不出一份像样的东西。

于是冒出一个念头：能不能让笔记直接长在网站上？写笔记这个动作本身，就是发布。

我的个人网站最终长这样：pz-maker.github.io——一个 AI 基础设施方向的学习 Wiki，有文章、周记、知识地图，还有一张会自动给互链文章连线的「知识星图」。而它的全部源码，就是我的 Obsidian 笔记库。

二、核心思路：让笔记库 = 网站仓库

网上大部分教程的做法是「Obsidian 写作 → 导出 → 转换 → 再发布」，中间隔着一层搬运。我反着来：直接把 Obsidian 的 vault 变成网站的源码仓库。

网站的内容目录就住在 vault 里，写笔记 = 改网站源码；
Git 仓库直接初始化在 vault 根目录；
在 Obsidian 里按一个快捷键，自动完成 commit + push；
GitHub Actions 监听到推送，自动构建、自动部署到 GitHub Pages。

整条链路上没有「导出」，没有「格式转换」，没有「复制粘贴」。这是整个方案里最重要的一个决定——一旦写作和发布共用同一套文件，发布的心智成本就趋近于零。

顺带解决了一个隐私问题：私人笔记和公开文章共存于同一个库。用一份白名单式的 .gitignore，只放行网站相关的目录，其余私人笔记永远不会被推送到网上。写作时不用在「可公开」和「不可公开」之间做心理切换，这在长期体验上非常关键。

三、选型复盘：我从 VitePress 掉头去了 Hugo

第一版站点我是用 VitePress（Vue 系的静态站点生成器）搭的，组件化、TypeScript，写着很顺手。但用了一段时间后，我把整站迁移到了 Hugo + 一款开源主题。复盘下来，理由有三：

我要的布局，别人已经写好了。我想要周记、动态、归档这类分区，Hugo 的主题开箱就有；在 VitePress 里每一个都得自己开发。
环境轻。Hugo 是单个可执行程序，不需要 node_modules，构建毫秒级；主题也直接复制进仓库，不依赖子模块。
frontmatter 零转换。Hugo 认的 title / date / categories / tags 字段，和 Obsidian 的 Properties 完全同构，模板自动生成，两边都认。

一条教训：技术选型的标准不是「什么火」，而是「我要的东西它自带多少」。自带的越多，你后期维护的就越少。

四、流水线的最终形态

现在我的发布流程是这样的：

text

Obsidian 写文章 ──▶ Ctrl+Shift+S ──▶ GitHub Actions 自动构建 ──▶ 上线
 （唯一要做的）      （一键推送）         （完全不用管）        （约 1 分钟）

真正让我坚持用下来的，是三个把摩擦降到最低的细节：

新建文章零手工：配了 Templater 模板，在 Obsidian 里 Ctrl+N 输入标题，文件夹结构、日期、分类默认值全部自动生成，我只管写正文。
图片即插即用：图片一律放文章同名文件夹，正文写相对路径。本地预览和线上渲染显示一致，从未出现「本地能看到、上线就 404」。
先预览再推送：本地跑一个 Hugo 预览服务，改完立刻看到渲染效果，确认没问题再按快捷键。所见即所得，上线零惊吓。

另外加了两个小彩蛋，让网站不至于只是「文章列表」：一个是霓虹高亮语法，写笔记时随手一个标签，渲染成青蓝色的发光文字；一个是知识星图——每篇文章是一颗星，正文里互相链接的文章自动连线，笔记攒得越多，星空越亮。这种「看得见的积累感」，正是我最初想要的东西。

五、踩坑实录（精华部分）

这部分是全文最值钱的地方，每一个都是真金白银的时间：

Obsidian 的 [[双链]] 网站不认。Hugo 的 Markdown 解析器默认不支持 wiki 链接语法，直接推上去就是死链。约定：站内引用一律用标准 Markdown 链接。这是迁移时批量转换的头号对象。
图片必须和文章同目录（所谓 page bundle）。放到别的目录里，本地预览正常、线上全部 404，非常隐蔽。
一个开关忘了开，所有高亮标签变成纯文本。Hugo 出于安全默认转义内嵌 HTML，允许自定义标签需要显式配置。症状是「代码没报错，样式全没了」，排查了我半天。
frontmatter 忘了写 date，文章排序全乱。缺省时 Hugo 会拿文件修改时间顶替，后果是文章列表顺序莫名其妙。解法是让模板强制生成日期，不给手滑留机会。
写完推送，网站上死活看不到文章。这是我写这篇文章的当天刚踩的：新建模板默认 draft: true，草稿在构建时会被整个跳过。发布前把 draft 改成 false 即可。反过来想，这其实是个保护机制——没写完的东西永远不会误上线。
推送失败不可怕。国内直连 GitHub 偶尔抽风，push 卡住是常态。关键是：提交已经安全地待在本地仓库里，什么都不会丢，等网络缓过来重试一次就好。理解了「本地提交 ≠ 远端推送」，就不会再为红字报错焦虑。
Obsidian 的 ==高亮== 网站不渲染。双等号是 Obsidian 的原生高亮语法，Hugo 的解析器不认，推上去会原样显示两个等号——这是我拿一篇测试文章实打实验出来的。站内要用约定的 HTML 标签写高亮。启示：编辑器的私有语法不要想当然地通用，任何新语法先本地预览再发布。

六、想明白的几件事

流水线跑顺之后，有三点体会超出了技术本身：

第一，最好的流程，是让「发布」没有摩擦的流程。 如果发布需要五个步骤，我大概率会攒着不发，然后不了了之。现在发布等于按一下保存键——写作的冲动出现的那一刻，它就已经在路上了。

第二，内容质量比数量重要得多。 网站上线后，我专门做了一次减法：删掉了一批 AI 生成的框架文章，只保留自己逐字敲过、真正消化了的内容。不是亲手写过的东西，挂在网上只是心虚的装饰。网站的价值密度，取决于你敢删多少。

第三，工具服务于内容，而不是反过来。 搭站的过程很容易上瘾——换主题、调配色、加特效，折腾一晚上一个字没写。我给这条线定的规矩是：折腾网站花的时间，必须少于写文章花的时间。工具链搭好之后，它最好的状态就是让你感觉不到它的存在。

如果你也在 Obsidian 里攒了不少笔记，不妨试试这条路：一个笔记库、一个 Git 仓库、一条 Actions 流水线，写和发之间，就只剩下一个快捷键的距离。

相关：文章常态化发布流程（站内速查卡）