Hugo & Obsidian 博客撰写 与 笔记记录 配置

还是喜欢Obsidian这种All in One的笔记软件，虽然大家都用Typora，但我喜欢把所有写作内容放在一块组织。
而且Obsidian可以实现电脑+手机的同步，这一点只在少数商业软件上有

在Obsidian中撰写Hugo文章

#

摸索了一下发现Obsidian支持软链接，所以只用把Hugo的文章目录软链接到Obsidian仓库下即可

ln -s path/to/hugo/content path/to/obsidian/vault/blog

然后就能在Obsidian中管理Hugo的文章了

另外需要关闭wiki link，让Obsidian使用标准的markdown语法

文章附件与目录结构

#

一开始配置Obsidian在每篇文章的父目录下的指定文件夹内存放附件，可以让Hugo和Obsidian都正确读取附件，但这会有一个问题
Obsidian对于粘贴进来的图片会重命名为Pasted image xxxx，在文章中会转义为Pasted%20image%20xxxx，虽然默认情况下Hugo能正确渲染图片，但是如果使用Hugo的Render Hooks来处理图片的话，是读取不到图片的。
假设你的Hook里使用这行代码来匹配文件：

{{ $img := .Page.Resources.Get .Destination}}

前半句.Page.Resources.GetHugo读取到目录下有这些文件：

attachments/Pasted image 20250927123804.png

但是用.Destination从文章中读取的路径是这样的：

attachments/Pasted%20image%2020250927123804.png

Hugo认为这两者是不相等的，所以是匹配不到文件的！而且Hugo也没有提供url转义的接口（虽然在Hugo Support里有用户发现Hugo有一个隐藏的接口，但对于这个场景来说没有实际意义）
考虑之后决定使用Custom Attachment Location这个插件来规范Obsidian的附件位置和文件名，还可以配置在md文章中的链接格式
我的配置如下：

文件名都是ascii字符，没有空格，不存在转义的问题
要想批量重命名之前的附件，只需要打开下面两个开关，然后重命名一下笔记就可以了
效果如下

要想清除没有使用的附件，可以使用Clear Unused Images这个插件
关于目录结构我建议一篇文章一个文件夹，文章放在index.md，附件放在attachments/*，对于Hugo来说就是页面资源

换行处理

#

Obsidian中是另起一行即为换行，但Hugo默认使用CommonMark语法，需要行尾打两个空格并换行才是换行，这很不方便，可以在Hugo的markup配置里启用硬换行
config/_default/markup.toml

[goldmark]
[goldmark.renderer]
hardWraps = true

Frontmatter配置

#

即Obsidian的笔记属性，可以自己配置个模板自动生成

Hugo图像处理

#

利用Hugo的Image render hooks实现图片自动转换webp并生成占位符以及图片懒加载
layouts/_default/_markup/render-image.html

{{ with .Page.Resources.Get .Destination }}
{{ with .Resize (printf "%dx%d webp" .Width .Height) }}
<img style="background-color: #fff1;"
     src="{{ .RelPermalink }}" 
     width="{{ .Width }}" 
     height="{{ .Height }}" 
     loading="lazy" 
     decoding="async"
     fetchpriority="low" 
     {{- with $.PlainText }} alt="{{ . }}" {{ end -}} 
     {{- with $.Title }} title="{{ . }}" {{ end -}}>
{{ end }}
{{ end }}

参考Hugo 图片懒加载和自适应 CSS 图片占位，相比于它的写法，这种实现方式更简洁
生成webp图片并启用懒加载可以加速页面首屏渲染时间，按需加载图片，节省流量（2025年了应该没有不支持webp的设备了吧…can i use）
指定图片的宽高并设置背景色可以在图片加载时显示一个同等大小的占位，避免布局偏移问题（表现为 点击目录跳转到标题之后并没有达到目标位置，因为在移动视图时文中的图片被加载了，撑大了内容高度），参见CLS分数
效果如下