Obsidian - Mapping Relationships Using Mermaid
Based on Josh Plunkett's video on YouTube. If you like this content, support the original creators by watching, liking and subscribing to their content.
Mermaid relationship mapping works in Obsidian without a plugin by embedding Mermaid syntax directly in Markdown.
Briefing
Mermaid diagrams can turn Obsidian notes into clickable relationship maps—without any extra plugin—by embedding Mermaid syntax directly in Markdown. The practical payoff is fast navigation: once nodes are styled as “internal links,” clicking a labeled box can jump to the corresponding note, making it easier to track complex connections like NPC ties, town geography, or quest routes.
The walkthrough starts by positioning Mermaid as Mermaid JS, a general-purpose diagram language used beyond Obsidian for flowcharts and other chart types. Obsidian’s built-in support means relationship mapping is available “out of the box,” but the tradeoff is that Mermaid’s power comes with code-heavy syntax. For beginners still learning headings and basic formatting, the workflow is likely too advanced; for people already comfortable editing Markdown, it becomes a structured way to model relationships.
A tour of diagram types follows, showing that Mermaid can generate more than simple graphs. Examples include left-to-right flowcharts, transit-like diagrams, flow-of-work visuals, pie charts, technical documentation-style diagrams, Gantt-style “gun charts,” and even more specialized visualizations like a day-in-the-life layout with tasks and satisfaction levels. The key takeaway is breadth: Mermaid can represent many relationship shapes, but the most immediately useful for note linking is the graph/flowchart approach.
The core mechanics are demonstrated with a code-first example. Nodes are declared with labels that correspond to note titles (e.g., “mum,” “dad,” “cis,” “bro,” “bro’s wife,” “the mailman”). Relationships are then created by connecting node identifiers using Mermaid graph syntax—solid lines for direct links and dotted lines for weaker or secret connections. The example builds a small family network and adds a dotted “sleeping around” connection between “bro’s wife” and “the mailman,” illustrating how line styles can encode meaning.
Clickable navigation requires an additional step: applying a “class” to the node identifiers and styling that class as an internal link (using Mermaid’s `class` and `internal-link` styling). Once configured correctly, hovering and control-clicking (or clicking, depending on Obsidian behavior) opens the linked notes, turning a static diagram into an interactive map.
The workflow also emphasizes practicality over reinvention. The creator recommends using templates and copying known-good Mermaid code from external examples—particularly a referenced vault of templates—then adapting node names and connections to the user’s own notes. The session closes by suggesting broader uses beyond relationships: mapping adventure paths, designing dungeons by linking rooms, and using different line types to represent one-way routes or hidden passages. A future alternative is hinted as a breadcrumbs-based approach, but Mermaid remains the focus for building a relationship chart that doubles as a navigation layer.
Cornell Notes
Mermaid embedded in Obsidian can build interactive relationship maps without plugins. Nodes are declared as labels tied to note titles, and edges connect those nodes using Mermaid graph syntax (including solid vs dotted lines to encode different kinds of relationships). To make nodes clickable, the diagram must apply a `class` to node identifiers and style it with `internal-link`, enabling hover and control-click navigation to the corresponding notes. The approach is code-heavy, so it’s best suited to users comfortable editing Markdown and Mermaid syntax. Once set up with templates, it becomes a fast way to model NPC networks, town layouts, quest routes, or even dungeon room connections.
How does Mermaid turn note titles into diagram nodes in Obsidian?
What’s the difference between declaring nodes and creating relationships?
How can Mermaid encode “secret” or weaker connections visually?
Why aren’t the diagram nodes clickable by default, and how are they made clickable?
What’s the practical workflow for building a relationship map without writing everything from scratch?
Beyond NPC relationships, what other mapping tasks fit Mermaid in Obsidian?
Review Questions
- What two-step process is required to go from labeled nodes to an interactive relationship map in Obsidian using Mermaid?
- How would you represent a one-way path versus a secret path using Mermaid edge styles, based on the example’s use of solid vs dotted lines?
- Why does using templates matter when working with Mermaid syntax in Obsidian, and what parts of the code are most likely to be customized?
Key Points
- 1
Mermaid relationship mapping works in Obsidian without a plugin by embedding Mermaid syntax directly in Markdown.
- 2
Mermaid supports many diagram types, but graph/flowchart syntax is the most directly useful for clickable note relationships.
- 3
Nodes must be declared first (as labeled identifiers tied to note titles), then edges must be added to create connections.
- 4
Solid and dotted edges can encode different relationship meanings (e.g., direct vs secret/indirect).
- 5
Clickable navigation requires applying `class` styling with `internal-link` so Obsidian treats nodes as internal note links.
- 6
Using external Mermaid/Obsidian template vaults reduces syntax errors and speeds up building custom relationship charts.
- 7
Mermaid diagrams can also plan adventure routes and dungeon room connections, not just NPC networks.