fix(frontmatter): tolerate leading whitespace before YAML delimiters

[rkdfx]

📑 Summary

YAML frontmatter is no longer rejected when the entire mermaid block sits inside indented HTML or markdown. Both space- and tab-indented delimiters now parse correctly, restoring the diagram instead of throwing "Syntax error in text".

Resolves #7613

📏 Design Decisions

  - /^-{3}\s*[\n\r](.*?)[\n\r]-{3}\s*[\n\r]+/s
  + /^([^\S\n\r]*)-{3}\s*[\n\r](.*?)[\n\r]\1-{3}\s*[\n\r]+/s

The \1 backreference is load-bearing: without it, an indented --- inside a multi-line YAML scalar (existing test) would be matched as the closing delimiter. js-yaml tolerates uniform space indents but rejects tabs, so the captured indent is stripped from each YAML line before parsing.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

🦋 Changeset detected

Latest commit: c8ba156

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	c8ba156
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69ff10270a7fe90008caf02d
😎 Deploy Preview	https://deploy-preview-7732--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7732

mermaid

npm i https://pkg.pr.new/mermaid@7732

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7732

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7732

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7732

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7732

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7732

commit: c8ba156

[codecov]

Codecov Report

❌ Patch coverage is 11.11111% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.29%. Comparing base (f50fb4f) to head (c8ba156).
⚠️ Report is 104 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagram-api/frontmatter.ts	0.00%	8 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #7732   +/-   ##
=======================================
  Coverage     3.29%   3.29%           
=======================================
  Files          561     560    -1     
  Lines        58576   58572    -4     
  Branches       873     873           
=======================================
  Hits          1928    1928           
+ Misses       56648   56644    -4     

Flag	Coverage Δ
unit	3.29% <11.11%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/diagram-api/regexes.ts	100.00% <100.00%> (ø)
packages/mermaid/src/diagram-api/frontmatter.ts	2.77% <0.00%> (-0.68%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	12 changed	May 9, 2026, 10:58 AM

[rkdfx]

The latest updates on your projects. Learn more about Argos notifications ↗︎
Build Status Details Updated (UTC)
default (Inspect) ⚠️ Changes detected (Review) 12 changed May 9, 2026, 10:58 AM

Hi, I'm not sure what to do for this, I'm not seeing any approve/reject option in argos review.

[knsv-bot]

[sisyphus-bot]

Thanks for this — the underlying root cause for #7613 (mermaid blocks rendered inside indented HTML/markdown losing their frontmatter) is a nicely diagnosed one, and the fix is tight. Tracing through the regex and dedent logic, everything lines up: the existing multi-line-scalar test case still passes because the scalar's --- is at a different indent than the opening ---, the asymmetric case where opening is flush but closing is indented is correctly rejected, and the \1 backreference does exactly what your inline comment claims it does. Nice work.

What's working well

🎉 [praise] The inline comment in regexes.ts explaining the \1 backreference (anchors closing --- to the same indent as the opening one, guards against indented --- inside multi-line YAML scalars) is exactly the kind of "WHY" comment that ages well — a future reader looking at this regex will immediately understand the load-bearing piece.

🎉 [praise] The test coverage is well-chosen — frontmatter.spec.ts:139, :151, :163, :181. Tab indentation, space indentation, config-with-indent (the Sankey repro), and the asymmetric "opening flush, closing indented" rejection case all in one go. The asymmetric case in particular is the kind of edge case that's easy to miss.

🎉 [praise] Good instinct to put the dedent step before yaml.load rather than trying to make js-yaml accept tab-indented documents. The if (indent) short-circuit also keeps the common no-indent case allocation-free.

Things to consider

🟢 [nit] frontmatter.spec.ts:183 — the asymmetric-rejection test only asserts on metadata, but it would be slightly stronger to also assert that text is preserved unchanged (i.e. that the function returns the early-return shape from frontmatter.ts:27-30). Something like:

expect(extractFrontMatter(text)).toEqual({ text, metadata: {} });

That way a future regression where the regex accidentally matches something but then yields an empty metadata wouldn't slip through.

💡 [suggestion] The dedent only strips indent from lines that startsWith(indent). That means a YAML line with inconsistent leading whitespace (e.g. opening delimiter indented with \t but a body line indented with ) is silently passed through to js-yaml at its original indent level. In practice users will be consistent, but it might be worth either a one-line comment noting the assumption, or a test case documenting what happens with mixed indentation so future-you knows it's intentional rather than a bug to "fix".

💡 [suggestion] Since frontMatterRegex is exported from regexes.ts and its capture group structure changed from [fullMatch, yamlBody] to [fullMatch, indent, yamlBody], this is technically observable by downstream consumers who import it directly. I checked the repo and the only other internal use (detectType.ts:38) uses .replace() with no group references so it's safe, and regexes.ts isn't part of the documented public API surface — so a patch bump is reasonable. Just flagging in case maintainers want to weigh in.

---

Out of scope for this PR but noted for future reference: the linked issue (#7613) is titled as a Sankey keyword problem, but the actual repro is "indented frontmatter inside HTML breaks rendering" — your changeset correctly describes the real root cause. Worth a comment on the issue clarifying the diagnosis before it closes, so anyone hitting the same symptom can find this fix.

Thanks again for the careful work and the thorough test coverage — this is the kind of focused, well-tested bug fix that's a joy to review. Approving.

[mermaid-bot]

@rkdfx, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.