Skip to content

Fix mermaid diagram rendering with YAML frontmatter#1913

Open
gjouret wants to merge 1 commit intoglushchenko:masterfrom
gjouret:fix/mermaid-yaml-frontmatter-rendering
Open

Fix mermaid diagram rendering with YAML frontmatter#1913
gjouret wants to merge 1 commit intoglushchenko:masterfrom
gjouret:fix/mermaid-yaml-frontmatter-rendering

Conversation

@gjouret
Copy link

@gjouret gjouret commented Mar 20, 2026

Summary

Mermaid diagrams that use YAML frontmatter (--- config blocks) fail to render in preview — they display as plain text code blocks instead of graphical diagrams. This PR fixes three root causes:

  • getPrettifiedContent() globally replaced \n---\n with \n<hr>\n, including inside fenced code blocks, destroying mermaid YAML frontmatter delimiters. Added replaceHorizontalRulesOutsideCodeBlocks() that uses regex to skip fenced code blocks.
  • cleanMetaData() stripped all --- separators when a note has YAML front matter. components(separatedBy: "---") splits on every occurrence, and list.joined() rejoined without the separator. Fixed with list.joined(separator: "---").
  • Mermaid v11 API and rendering improvements: Updated from deprecated mermaid.init() to async mermaid.run(), bundled @mermaid-js/layout-elk plugin for ELK layout support, added YAML frontmatter indentation normalization (tabs/mixed whitespace → consistent spaces), changed useMaxWidth to true so diagrams fit the preview width, and added visible error messages on render failure.

Example mermaid that now renders correctly

```mermaid
---
title: My Diagram
config:
  theme: forest
  layout: elk
---
flowchart LR
    A["Node A"] --> B["Node B"]
```

Test plan

  • Create a note with a mermaid diagram that has YAML frontmatter (including layout: elk) — verify it renders as a graphical diagram
  • Create a note with a simple mermaid diagram (no frontmatter) — verify it still renders
  • Create a note with YAML front matter (---\ntitle: ...\n---) AND a mermaid diagram with its own --- frontmatter — verify both are handled correctly
  • Verify complex diagrams fit within the preview width (no horizontal overflow)
  • Verify that non-mermaid code blocks containing --- are unaffected

🤖 Generated with Claude Code

Mermaid diagrams using YAML frontmatter (--- config blocks) failed to
render in preview, showing as plain text code blocks instead of
graphical diagrams. Three issues were identified and fixed:

1. Horizontal rule replacement destroyed mermaid frontmatter:
   getPrettifiedContent() globally replaced \n---\n with \n<hr>\n,
   including inside fenced code blocks. Added
   replaceHorizontalRulesOutsideCodeBlocks() to skip code fences.

2. cleanMetaData() stripped --- separators from content:
   When a note has YAML front matter, components(separatedBy: "---")
   splits on ALL occurrences, and list.joined() rejoined without the
   separator, destroying --- inside mermaid blocks. Fixed by using
   list.joined(separator: "---").

3. Mermaid v11 API and rendering improvements:
   - Updated from deprecated mermaid.init() to mermaid.run() (async)
   - Bundled @mermaid-js/layout-elk plugin for ELK layout support
   - Added YAML frontmatter indentation normalization (tabs → spaces)
   - Changed useMaxWidth from false to true (diagrams fit preview width)
   - Added error handling with visible error messages on render failure
   - Removed async script loading to prevent race conditions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant