Obsidian 静态发布方案选择

从 Obsidian Vault 发布为 Web 知识站时，比较 Quartz、MkDocs、Digital Garden 等路径在 WikiLink/知识图谱、内容筛选、构建维护和站点定制上的差异。

#obsidian #synthesis #growing

[!info] related notes

上层架构: Obsidian 同步、版本控制与发布架构

Quartz: Quartz 静态部署指南

Digital Garden: Obsidian Digital Garden 插件指南

Git: Obsidian Git 插件指南

文件命名: Obsidian 笔记标题与文件名

Obsidian 静态发布方案选择

先定义问题

目标不是“找最强静态站工具”，而是把 Vault 投影成一个 Web 站点：

Obsidian Vault
→ select public content
→ transform Obsidian Markdown
→ build site
→ deploy

工具选择取决于你需要保留多少 Obsidian 语义。

选择维度

优先比较：

WikiLink 支持；
backlink / graph；
callout / embed / attachment；
public/private selection；
build complexity；
theme / component customization；
search；
hosting freedom；
migration cost。

Quartz

Quartz 更偏：

把 Markdown Vault 组织成 digital garden / knowledge graph style static site。

适合：

WikiLink；
backlinks；
graph/navigation；
知识库而非传统线性博客；
希望源码和构建流程可控。

代价是：

Node/build toolchain；
theme/config 维护；
升级要关注 Quartz 自身变化。

具体安装与部署放在 Quartz 静态部署指南。

MkDocs

MkDocs 更偏：

结构化技术文档站。

适合：

明确导航层级；
文档型内容；
Markdown → docs site；
Python/doc tooling 生态。

如果 Vault 大量依赖 Obsidian WikiLink、graph、特殊 embed，则需要额外转换或插件。

所以：

Documentation-first
→ MkDocs 往往自然

Knowledge-graph-first
→ Quartz 往往更自然

Digital Garden 发布路径

Digital Garden 类插件更偏：

从 Obsidian 中选择笔记并直接进入发布工作流。

它的核心优势不是“静态生成器最强”，而是 authoring → publish 的距离短。

适合：

选择性公开；
希望主要在 Obsidian UI 中控制发布；
不想自己管理太多静态站构建细节。

具体操作看 Obsidian Digital Garden 插件指南。

Hexo / 通用博客生成器

传统博客工具更适合：

时间线文章；
category/tag；
theme；
blog archive。

如果原 Vault 本质是知识图谱，则迁移成本常来自：

WikiLink；
backlink；
attachment；
note graph；
非博客型导航。

所以不应该只比较“主题多不多”。

选型矩阵

需求	更自然的方向
Obsidian 知识图谱语义	Quartz
文档站/手册	MkDocs
Obsidian 内直接选择发布	Digital Garden workflow
传统博客	Hexo / 通用 blog SSG
高度自定义应用	自建 Markdown content pipeline

这里是问题匹配，不是质量排名。

Public Projection

无论选什么工具，都应先定义：

private vault
→ publication policy
→ public projection

不要默认：

git tracked
= public

常见 public policy：

explicit publish flag；
public folder；
whitelist；
build-time filter。

其中一种作为唯一规则即可，避免多套规则互相冲突。

链接转换

Obsidian：

[[cors]]
[[cors|CORS]]
![image](/vault-assets/image.png)

Web generator 需要把它们映射为：

URL；
anchor；
image asset；
backlink。

因此发布工具真正的核心兼容性问题是：

能否稳定投影 Vault 的内容模型。

Source 与 Generated Output

必须保持：

Markdown source
→ deterministic build
→ generated site

Generated output 应该可以删除后重新生成。

如果你需要手工修改生成后的 HTML 才能正常发布，说明 source/build boundary 已经失效。

发布前检查

常见误区

GitHub Pages 就是生成器

Pages 是 hosting/deployment surface，不负责定义你的 Obsidian 内容转换模型。

Quartz 和 Obsidian Sync 是竞争产品

它们解决不同层：

Sync：编辑副本同步；
Quartz：发布构建。

所有 Vault 都应该发布

私人知识库与 public garden 可以拥有完全不同的内容范围。

学习检查

不看正文回答：

静态发布链路的四步是什么？
Quartz、MkDocs、Digital Garden 的主要问题空间分别是什么？
为什么“WikiLink 能不能稳定转换”比“主题数量”更核心？
public projection 为什么必须和 Git tracking 分开？
为什么 generated HTML 应该可删除并重新构建？
给一个“教程型文档库”和一个“原子知识图谱库”，分别说明更适合哪类发布路径及理由。