Mermaid 在 Obsidian 中:原生渲染、主题与移动端一致性

Obsidian 如何渲染 Mermaid

Obsidian 原生支持渲染语言标记为 mermaid 的围栏代码块——无需任何插件。图表在阅读视图和实时预览中都会显示。

Mermaid 版本随应用一起打包,所以会随 Obsidian 的更新而更新。桌面端和移动端的发布版本有时会短暂不一致,这偶尔会导致同一个图表在一台设备上能渲染、在另一台上却失败。

```mermaid
mindmap
  root((仓库))
    笔记
    图表
    模板
```

哪些效果不错

Obsidian 往往携带相对较新的 Mermaid 版本,所以较新的图表类型常常在 Obsidian 里率先可用,早于 GitHub 或 Notion。

图表会继承仓库(vault)的主题。社区主题和 CSS 代码片段可以重新定义 Mermaid 输出的样式,这对个人知识库来说是很强大的能力。

需要留意的地方

主题和 CSS 片段的样式只对你自己的仓库生效:一个在你的环境里看起来很棒的图表,对其他人来说会以默认样式渲染,粘贴进 GitHub 或 Notion 后又会是另一副模样。

click 指令及其他交互功能受应用安全设置的限制;不要依赖它们。

各种发布管线(Obsidian Publish、静态站点导出工具、同步到其他工具)都会用各自的版本和规则来渲染 Mermaid——请针对你发布链路里最薄弱的目标环境去验证,而不是只针对 Obsidian 本身。

在移动端,复杂图表可能会比较卡顿,双指缩放大型流程图的体验也不太顺手——更小的图表能带来更好的阅读体验。

推荐工作流

在 Obsidian 里可以放心创作——它是支持能力最强的 Mermaid 宿主之一。风险在下游:那些后续会被搬到 GitHub、GitLab、Notion 或博客上的笔记。

在图表离开你的仓库之前,用匹配目标平台的预设在 MermaidPen 的 Studio 里过一遍,应用安全修复,如果目标平台不太可靠,就导出 SVG 或 PNG。