使用嵌套流程图子图创建带标题的容器，包括叶子块。当空容器的渲染效果不佳时，可在每个叶子块内添加一个不可见的占位符。这能保留可见的层级结构；请在已安装的 Obsidian 渲染器中检查效果。

本指南构建一个中性的示意图：一个名为 Collection 的外层块，其中包含 Group A 和 Group B，每个组内都有带标题的叶子容器。目标是让这些叶子块保持带标题的容器外观，而不是将它们替换成普通的带标签矩形。

带标题的叶子块应该用什么表示？

无论是否包含其他有意义的块，都用 subgraph 表示每个可见容器。Mermaid 在流程图示例中介绍了子图、显式子图 ID 和嵌套结构。普通节点声明（如 leafA["Block A"]）会创建带标签的节点；它并不声明带标题的容器。请参阅 Mermaid 的流程图 — 基本语法。

在此示例中，请区分可见模型与布局辅助元素。Collection、各组和叶子块是有意义的元素。占位符是用于为叶子容器提供布局内容的实现细节。添加这个辅助元素不会将叶子块的声明从子图变成节点。

这种区分也明确了此方法的适用边界：它生成的图表中，可见的叶子块仍是带标题的容器，但源代码中包含普通辅助节点。如果你的要求禁止所有节点声明，包括不可见的辅助节点，那么这个变通方法就不符合更严格的要求。

检查 Mac 安装使用的渲染器

在 Obsidian 中，从侧边栏打开 Settings，然后选择 General 并记下应用版本。Obsidian 的设置文档指出，版本信息位于 General 中。选择相关发行说明时，请使用该版本。

渲染器存在一个重要区别。2026 年 10 月 22 日的官方发行说明将桌面版 1.15.0 标记为早期访问版，并说明它通过 Obsidian 的 Pele 库渲染 Mermaid 语法，同时兼容 Mermaid 12.1.0 语法。该版本还将生成的图表类更改为 Pele 的类。不要假设旧版安装使用 Pele，也不要认为兼容就意味着输出与 Mermaid.js 完全相同。请参阅 Obsidian 1.15.0 桌面版（早期访问）。

本指南检索到的 Mermaid 文档显示版本为 12.2.0。这与 Obsidian 发行说明中提到的兼容级别是两个不同的版本。在分别检查各环境中的同一个示例之前，请将文档、在线编辑器和已安装的应用视为彼此独立的环境。

首次尝试时，请勿在图表中加入特定于渲染器的配置或外部样式表选择器。下面的示例使用子图和图表内样式，为你提供一个简洁的起点，以便检查自己的安装环境。

在 Obsidian 笔记中构建嵌套容器

在编辑视图中打开一篇笔记，粘贴下面的完整代码块，包括开头和结尾的围栏。Obsidian 将 Mermaid 图表记录为带有语言标识符 mermaid 的围栏代码块。此文档格式不需要额外的图表插件。请参阅高级格式语法。

```mermaid
flowchart TB
    subgraph collection["Collection"]
        subgraph groupA["Group A"]
            subgraph blockA["Block A"]
                spacerA[" "]
            end
            subgraph blockB["Block B"]
                spacerB[" "]
            end
        end
        subgraph groupB["Group B"]
            subgraph blockC["Block C"]
                spacerC[" "]
            end
        end
    end

    classDef spacer fill:transparent,stroke:transparent,color:transparent;
    class spacerA,spacerB,spacerC spacer;
```

按 Cmd+E 在编辑视图和 Reading view 之间切换。在阅读视图中检查完成的图表，避免编辑光标显示其源代码。Obsidian 的视图和编辑模式文档介绍了这些控件。

预期结果应包含六个可见的带标题容器：一个集合、两个组和三个叶子块。每个叶子块都包含一个标签为单个空格的辅助元素。spacer 类请求使用透明填充、边框和文本。这结合了 Mermaid 文档介绍的类机制与一种布局变通方法；Mermaid 在其流程图样式参考中介绍了 classDef 和类分配。

本示例已根据文档中的语法进行检查；本文并未在 Mac 上的 Obsidian 环境中实际渲染它。因此，验收标准是本地的视觉检查：六个标题都应显示，每个组都应包含分配给它的叶子块，而且不应看到占位矩形。精确的间距和同级元素的位置不属于验收标准。

修改标签而不改变层级

先只修改引号中的标题。保持 collection、groupA、blockA 和其他 ID 各不相同。这样更容易将编辑后的版本与起始示例进行比较。

若要添加另一个叶子块，请复制一个完整的叶子子图，为其子图和占位符分别指定新的 ID，并将新占位符的 ID 添加到最后的类分配语句中。将它放在其所属组的 end 之前。例如，Group B 中的第四个叶子块应与 blockC 并列，并位于 groupB 内。

从内向外阅读闭合语句：先关闭叶子块，再关闭所属组，最后关闭集合。缩进能让你在编辑时看清结构，但源代码必须正确表达每个 end 的位置。

为什么要使用占位符，而不是空子图？

空容器的行为会因渲染器和版本而异。Mermaid 问题 5402 报告称，在 Mermaid 10.8.0 中使用 ELK 时，空子图无法正常工作，而提供的 Dagre 示例可以正常工作。这是针对特定设置的历史报告，并不能证明所有当前渲染器都会拒绝空子图。请参阅ELK 渲染器无法处理空子图。

实际的推论是：如果图表面向未知的安装环境，就不要让其完全依赖空容器行为。占位符方法会为每个叶子块提供明确内容，同时将有意义的标题保留在子图上。

选择源代码严格程度时，可参考以下决策表：

要求 起始方法 检查内容
可见的叶子块必须保持为带标题的容器 使用嵌套子图和透明占位符 标题、包含关系以及隐藏的辅助元素
源代码不得包含辅助节点 在目标渲染器中尝试空的叶子子图 每个空叶子块是否都能正常渲染
之后会在叶子块中加入实际内容 保留叶子子图并替换占位符 仅移除不再需要的辅助元素
块需要明确的列布局 单独评估 Mermaid 块图 已安装版本的语法支持和标题呈现方式

Mermaid 的专用块图文档介绍了复合块、列和显式间距。当布局是主要任务时，值得评估这些功能。但这些功能本身并不能保证转换后仍会保留这种特定的带标题容器呈现方式。请参阅块图文档。

排查显示异常的结果

每次只更改一项内容。在单独的笔记中保留完整的起始示例副本，这样就能区分渲染器差异和编辑错误。

  1. 笔记显示的是代码而不是图表。 检查开头的围栏是否使用 mermaid，然后切换到 Reading view。将围栏格式与 Obsidian 文档中的图表格式进行比较。
  2. 叶子块看起来像普通的带标签矩形。 检查它的声明。它应以 subgraph 开头，且占位符应另起一行，放在其中。
  3. 叶子块内部仍然显示一个小矩形。 检查占位符 ID 是否与最后的 class 语句一致。暂时移除样式以确认你看到的是哪个辅助元素，然后恢复样式。
  4. 块出现在错误的组中。 在调整布局设置之前，先检查 end 闭合语句的顺序。
  5. 图表在线上可用，但在 Obsidian 中显示不同。 对照已安装应用的发行说明和在线渲染器的版本。将本地可正常工作的示例保留为参考。

先保留包含关系，再调整布局

标题和包含关系正确后，再判断布局是否足够清晰。不要仅仅为了缩小矩形就将叶子子图替换成节点：这种修改会改变你原本要保留的表示方式。

同样，只有在图表需要表达超出包含关系的关联时，才添加连接线。Mermaid 文档说明了一项方向限制：如果将子图内部的节点链接到外部，该子图就会继承其父级的方向。添加此类连接线后，请重新检查布局。请参阅子图中的方向。

最后，在你通常阅读笔记时使用的宽度下检查笔记。保留能清楚呈现集合、各组及其带标题叶子块的版本。理想结果应是清晰易读的包含层级，叶子块仍然是子图，同时你能明确了解不可见的布局辅助元素，并在之后轻松移除它们。

来源