静态站点发布方案

Obsidian Publish 很省心，但省心的代价是每月 $8-10，以及”框架之内”的自由度。如果你愿意花一点折腾的力气，自建静态站点能换来三样 Publish 给不了的东西：免费、完全可控、极致可定制。

静态站点生成器（Static Site Generator，SSG）的工作方式很朴素：把一堆 Markdown 文件编译成 HTML，丢到任意一个静态托管平台上（Cloudflare Pages、GitHub Pages、Netlify、Vercel），站点就跑起来了。托管本身几乎都免费，你拥有全部源码，想怎么改就怎么改。

但问题来了：Obsidian 用的不是”普通” Markdown，它有一整套自己的方言。把 Obsidian 笔记喂给普通 SSG，会撞上五道坎。

五道坎：Obsidian 方言的兼容难题

第一道，双链 [[ ]]。 Obsidian 用 [[笔记名]] 互相链接，而标准 Markdown 只认 [文本](路径)。SSG 得能识别方括号、按文件名解析目标、生成正确的 URL，最好还能处理别名 [[页|别名]]、标题锚点 [[页#标题]]、块引用 [[页#^block]]。

第二道，嵌入 ![[]]。 ![[笔记]] 在 Obsidian 里是把整篇笔记”嵌入”当前页，![[图片.png]] 是嵌入图片。SSG 需要把前者转成内联渲染、把后者转成标准图片标签，还要支持 ![[图.png|宽x高]] 这样的尺寸控制。

第三道，Callout。 > [!note] 这套标注语法是 Obsidian 独有的，标准 Markdown 里没有。不做处理就会原样输出成一段奇怪的引用块。

第四道，属性（Properties）。 Obsidian 的 YAML frontmatter 字段（别名、标签、发布状态）需要被正确解析并用于排序、过滤、展示。

第五道，Dataview。 社区插件 Dataview 的查询结果是动态生成的，静态站点无法运行 JS 查询，只能在发布前把结果”快照”成静态内容。

这五道坎，决定了不同 SSG 对 Obsidian 的友好程度。我们来看五条主流路线。

Quartz：为 Obsidian 而生

Quartz 最初就是为”把 Obsidian 库发布成网站”而设计的，至今仍是 Obsidian 用户自建花园的首选。它开箱即用搭载了 ObsidianFlavoredMarkdown 插件，几乎原样支持上面五道坎的全部语法：

• 双链：所有变体——[[页]]、[[页|别名]]、[[页#标题]]、[[页#^块]]——统统支持，还能配置链接解析行为匹配 Obsidian。
• 嵌入：![[笔记]] 嵌入笔记、![[图片]] 嵌入图片、![[图|alt 宽x高]] 带尺寸，一应俱全。
• Callout：全部内置类型（note、tip、warning、danger……）及可折叠变体都支持。
• 高亮 ==文本==、注释 %%隐藏%%、标签 #tag、块引用 ^block-id、Mermaid 图表——全支持。
• Dataview：通过社区插件 Quartz Syncer，在同步时把查询结果导出为静态内容。
• 甚至支持 Excalidraw、Leaflet 地图等社区插件内容。

Quartz 需要 Node v22，三行命令即可建站：git clone、npm i、npx quartz create，然后部署到 GitHub Pages、Cloudflare、Netlify 或 Vercel。它还内置全文搜索、图谱视图、反向链接、悬停预览——几乎是 Publish 的开源平替。

MkDocs：文档站老兵

MkDocs 是 Python 生态的文档站生成器，搭上 Material 主题后颜值与功能俱佳。通过社区模板和插件（如 mkdocs-obsidian-interactive 之类），它能支持 Obsidian 风格的 wikilinks 解析，并支持深浅色主题切换。MkDocs 的强项是结构化文档——用它做项目文档、教程站很合适，但 Obsidian 语法的支持不如 Quartz 原生，需要额外配置，Callout 和嵌入往往要自己写插件适配。

VitePress：Vue 驱动的极速文档

VitePress 基于 Vite 与 Vue，构建极快，是 Vue 官方文档的同款引擎。它对标准 Markdown 支持优秀，内置了 Mermaid、代码组、容器（container）等扩展，但容器语法是 ::: tip 而非 Obsidian 的 > [!tip]。VitePress 默认不认 [[wikilinks]] 和 ![[]] 嵌入，需要自行编写 markdown-it 插件来转换。它适合 Vue 用户和技术文档，对 Obsidian 方言的亲和力最弱。

Astro：群岛架构，灵活至上

Astro 是近两年风头最劲的前端框架，“群岛架构”让它在默认零 JavaScript 的同时，又能按需激活交互组件。Astro 内置 Markdown 支持，更强大的 Content Collections 能给笔记定义 schema、做类型校验、按属性查询排序。它对 Obsidian 语法的支持需要通过 remark 插件来补齐——社区有 remark-obsidian、remark-wiki-link 等插件可组合使用。Astro 的优势是定制自由度极高：任何 UI 框架（React、Vue、Svelte）都能嵌入，搜索、目录、暗色模式全可自由搭建。代价是要自己处理语法兼容。下一章我们会用它配 Cloudflare 走一遍完整流程。

Eleventy：极简主义者的画布

Eleventy（11ty）是 Node 生态里最”无框架”的 SSG，不绑定任何前端框架，纯粹用模板语言（Nunjucks、Liquid 等）渲染。它极其轻量、极其灵活，但也意味着”什么都要自己来”——wikilinks、嵌入、callout 都得靠自制插件或预处理脚本。Eleventy 适合喜欢从零搭建、追求极致可控的开发者，对非技术用户不太友好。

一张速查表

方案	Obsidian 语法支持	上手难度	适合人群
Quartz	开箱即用，最全面	低	想要 Publish 平替的 Obsidian 用户
MkDocs	需插件，中等	中	项目文档、教程站
VitePress	需自制插件，弱	中	Vue 用户、技术文档
Astro	需 remark 插件，灵活	中高	想要深度定制的开发者
Eleventy	全靠自己，最灵活	高	极简主义开发者

如果你的首要诉求是”省心且像 Publish”，选 Quartz；如果首要诉求是”我要把站点做成任何我想要的样子”，选 Astro。下一章，我们就以 Astro + Cloudflare 为例，把这套自建路线从零走通——你正在浏览的这个教程网站，正是用同一条路铺成的。