Fix non-markdown labels in flowcharts being treated like markdown

[darshanr0107]

📑 Summary

This PR fixes a regression introduced in #5604 (Mermaid v11.0.0) where all flowchart labels were being treated as markdown by default, causing rendering issues and breaking backwards compatibility with Mermaidv10diagrams. The fix ensures that only labels explicitly marked as markdown (e.g. node["`_markdown_ **text**`"]) are processed as markdown, while plain text labels are rendered as regular text.

Note

This PR currently focuses only on flowcharts. Other diagram types will be handled in future work.

Tip

If you want markdown formatting, you can still use markdown in your flowchart labels by using the proper markdown syntax.
Wrap your markdown text with double quotes and backticks: node["`_markdown_ **text**`"]

Example:

flowchart LR
    plain["Plain text label"]
    markdown["`This is **bold** markdown`"]

Resolves #5824
Related to #6048(fixes the issue for flowcharts only)
Related to #6275(fixes the issue for flowcharts only)

Related PR's #6345 , #6087

Why This Is An Issue

When all labels are treated as markdown by default, several critical problems arise:

1. Line Wrapping Issues

• Markdown processing applies automatic text wrapping based on width constraints
• Plain text labels in flowcharts (without markdown syntax) now render as regular text

2. Text Interpretation Errors

• > something and - something can be valid math expressions (greater-than or minus),but markdown would instead render them as a quote/unordered list item.
• Ordered list patterns like 50. x and 100. y are often numeric expressions, but Markdown will auto-renumber them (e.g., 50. x → 50. x, 100. y → 51. y).

3. Backwards Compatibility Broken

• Mermaid v10diagrams that worked perfectly now fail or render incorrectly
• No migration path for existing diagrams
• Blocking GitLab from upgrading tov11: https://gitlab.com/gitlab-org/gitlab/-/issues/491514

📏 Design Decisions

1. Label Type Propagation Through the Rendering Pipeline

• Propagate labelType from parser → database → rendering functions
• Parser already correctly identifies markdown v/s plain text labels
• The parser already correctly identifies markdown v/s plain text labels, this just ensures it's passed to the renderer

2. Dual Rendering Paths Based on Label Type

• Use conditional logic to choose between createText() (markdown) and createLabel() (plain text)
• createText() handles markdown processing with wrapping and parsing
• createLabel() handles plain text with proper multiline support

3. Markdown Flag in createText()

• Add a markdown boolean parameter with default true
• Maintains backwards compatibility (default behavior is markdown)
• Allows explicit control over markdown processing
• Enables rendering system to pass correct flag based on labelType

4. Automatic Line Wrapping for plain text

• Plain text node labels and edge labels in flowcharts will automatically line-wrap. Although this isn't backwards compatible with v10, we think this is a minor change and it's worth keeping to avoid too many changes from diagrams created from v11 onwards.
• Plain text labels in other diagram types will continue to not automatically line-wrap.

Flowchart-Specific Fix (Why Not All Diagram Types)

As flowcharts are the most common mermaid diagram, fixing this for flowcharts first would have the highest amount of impact. And additionally, since the grammar and documentation already distinguish between markdown ("`markdown`") and plain text "plain text", it's also the least amount of effort for both us and users to fix.

I've made sure that all other diagram types remain using their current behaviour, so we can fix them in separate PRs.

📋 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: dc7e7d8

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

[codecov]

Codecov Report

❌ Patch coverage is 0% with 115 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.55%. Comparing base (5959fc0) to head (dc7e7d8).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
...aid/src/rendering-util/rendering-elements/edges.js	0.00%	32 Missing ⚠️
packages/mermaid/src/dagre-wrapper/edges.js	0.00%	18 Missing ⚠️
packages/mermaid/src/diagrams/flowchart/flowDb.ts	0.00%	16 Missing ⚠️
...c/rendering-util/rendering-elements/shapes/util.ts	0.00%	15 Missing ⚠️
.../src/rendering-util/rendering-elements/clusters.js	0.00%	11 Missing ⚠️
...mermaid/src/rendering-util/handle-markdown-text.ts	0.00%	10 Missing ⚠️
packages/mermaid/src/diagrams/class/classDb.ts	0.00%	2 Missing ⚠️
packages/mermaid/src/diagrams/er/erDb.ts	0.00%	2 Missing ⚠️
packages/mermaid/src/diagrams/kanban/kanbanDb.ts	0.00%	2 Missing ⚠️
packages/mermaid/src/diagrams/state/dataFetcher.ts	0.00%	2 Missing ⚠️
... and 5 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7276      +/-   ##
==========================================
- Coverage     3.56%   3.55%   -0.01%     
==========================================
  Files          489     489              
  Lines        48664   48729      +65     
  Branches       765     765              
==========================================
  Hits          1734    1734              
- Misses       46930   46995      +65     

Flag	Coverage Δ
unit	3.55% <0.00%> (-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/diagrams/er/erTypes.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/flowchart/types.ts	100.00% <ø> (ø)
...kages/mermaid/src/diagrams/mindmap/mindmapTypes.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/state/stateDb.ts	0.00% <ø> (ø)
packages/mermaid/src/types.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/block/styles.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/mindmap/mindmapDb.ts	0.00% <0.00%> (ø)
.../mermaid/src/diagrams/requirement/requirementDb.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/state/stateCommon.ts	1.19% <0.00%> (ø)
packages/mermaid/src/rendering-util/createText.ts	0.43% <0.00%> (ø)
... and 10 more

🚀 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	5 changed, 4 added	Feb 27, 2026, 9:13 AM

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	dc7e7d8
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69a15d9591013f00084aa368
😎 Deploy Preview	https://deploy-preview-7276--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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@7276

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 0d38a5e

[ashishjain0512]

[sisyphus-bot] Review of PR #7276

What's working well

🎉 [praise] Great architectural approach — switching from "everything is markdown by default" to explicit opt-in via labelType is the right direction. The strategy of adding labelType: 'markdown' to all other diagram DBs (class, ER, kanban, mindmap, requirement, state) preserves their existing behavior while letting flowcharts handle label types correctly. This is a clean, defensive change.

🎉 [praise] Excellent PR description. The "Why This Is An Issue" section with concrete examples of how markdown misinterprets plain text (> something → blockquote, - x → list item, 1. → ordered list) makes the regression immediately clear. This is the kind of write-up that makes reviews much easier.

🎉 [praise] Good scoping discipline — limiting the fix to flowcharts with an explicit note about future work keeps this PR reviewable and reduces regression risk.

🎉 [praise] The new e2e test for edge label auto-wrapping (flowchart-v2.spec.js) testing multiple config combinations (markdownAutoWrap × htmlLabels) is thorough. The flowchart.spec.js additions covering mixed string/markdown labels and subgraph headings with list-like text ("1. first", "2. second") directly target the reported regression.

Things to address

🟡 [important] — handle-markdown-text.spec.ts:205: The skipped unit test ("No auto wrapping") and the commented-out e2e config {markdownAutoWrap: false, htmlLabels: false} in flowchart-v2.spec.js:82 both have TODO comments but no tracking issues. These tend to get lost without a filed issue. Would you be open to filing a quick follow-up issue to track the markdownAutoWrap: false, htmlLabels: false bug? The code comment in handle-markdown-text.ts:20-22 explains the root cause (splitWordToFitWidth splits even when spaces should be preserved), which is great context for whoever picks it up.

🟡 [important] — Two separate changesets (curvy-cases-battle.md and swift-cloths-run.md) for a single PR is a bit unusual. The first describes the markdownAutoWrap fix (which is really a side effect of the main fix), and the second describes the main fix. Since they'll both produce separate changelog entries for the same patch bump, it might be cleaner to consolidate into one changeset that covers both aspects. Not blocking, but worth considering.

🟢 [nit] — Agreeing with @aloisklink's earlier suggestion on sanitizeNodeLabelType (flowDb.ts:89). The name implies security sanitization, but it's really type validation/coercion. castLabelType or validateLabelType would communicate the intent more clearly. Fine as a follow-up.

💡 [suggestion] — nonMarkdownToHTML (handle-markdown-text.ts:96) wraps output in <p> tags, and block/styles.ts adds .edgeLabel p { display: inline } to compensate. The flowchart styles.ts doesn't have this rule — if non-markdown edge labels in flowcharts render with unexpected block-level spacing, this could be why. The Argos screenshots should catch it, so this may already be fine, but worth a quick check.

Summary

Solid fix for a significant v10 → v11 regression. The approach is architecturally sound and well-tested. The shared rendering-util changes (createText.ts, handle-markdown-text.ts, clusters.js, edges.js, shapes/util.ts) are the highest-risk area, but the explicit labelType: 'markdown' additions to other diagram types provide a good safety net. The Argos visual diffs (5 changed, 4 added) are the key signal for cross-diagram regression — as long as those look expected, this is in great shape.

[aloisklink]

Your latest changes, where we autowrap plain text labels in flowcharts, but not plain text labels in other diagram types, looks okay to me too.

I'm a bit worried that some v10 users might complain about it--especially since we don't have an equivalent markdownAutoWrap: false setting to disable this--but I do agree with you that it'll probably prevent less complaints with people that are used to the post-v11 system of linewrapping by default, and we can always considering changing it later if there are complaints about it.

[ashishjain0512]

@darshanr0107 I think this PR is a step in the right direction, and we should follow-up markdown & autowrap handling for other diagrams in separate PR. I will merge this now.